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Preface 


Intended Audience 

This document describes VAX RMS control blocks and services for 
programmers. 


Structure of This Document 

This document consists of four parts and two appendixes. 

• Part I contains general information in four sections: 

— Section 1 introduces the reader to VAX RMS functions and associated 
control blocks. 

— Section 2 discusses the VAX RMS program interface that applies to 
using any VAX programming language. 

— Section 3 describes the program interface with VAX MACRO, including 
how to use VAX RMS macros. This information will also be of interest 
to advanced programmers using other VAX programming languages. 

— Section 4 describes the groups of VAX RMS services and provides VAX 
RMS example programs using VAX MACRO. 

• Part II describes the VAX RMS control blocks and their associated fields, 
in Section 5 through Section 15. This information is intended for a 
programmer using any VAX programming language. 

• Part III describes the VAX RMS services, including the control block fields 
accessed by each service. This information is intended for a programmer 
using any VAX programming language. 

• Appendix A lists VAX RMS messages. 

• Appendix B contains the formats and associated usage notes for the VAX 
RMS control block initialization and store macros used by VAX MACRO 
programmers. Note that this material was formerly located in Part III. 

Notes 

1 The three sections describing the SYS$RMSRUNDOWN, SYS$SETDDIR, 
and SYS$SETDFPROT services have been moved from this manual to the 
VAX/VMS System Services Reference Manual. 

2 The VAX RMS services descriptions formerly located in Part IV are now 
located in Part III. 

3 The descriptions of the VAX RMS macros that were previously located 
in Part III are now located in Appendix B. 
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Associated Documents 

The following documents contain information related to this reference 

manual: 

• The Introduction to VAX/VMS System Routines and the VAX/VMS System 
Routines Reference Volume contain information about the calling routines 
on a VMS system. 

• The Guide to VAX/VMS File Applications contains related information 
about VAX RMS, FDL, and the use of files 

• The VAX/VMS Networking Manual discusses the support of VAX RMS 
options for remote file access to non-VAX/VMS systems. For example, 
when the remote system is a PDP-11 system running RMS-11, Prolog 3 
index files are not supported and certain VAX RMS Key Definition XAB 
fields are not fully supported, as well as other control block fields. The 
support for remote file access between VAX/VMS systems is described 
in Part II of this manual for each applicable control block field and in the 
VAX/VMS I/O Reference Volume . 


Conventions Used in This Document 


Convention 

[ret] 


|CTRL/x| 


$ SHOW TIME 
05-JUN-1986 11:55:22 

$ TYPE MYFILE.DAT 


file-spec, . . . 


[logical-name] 


quotation marks 
apostrophes 


Meaning 

A symbol with a one- to six-character 
abbreviation indicates that you press a key 
on the terminal, for example, I RET | . 

The phrase CTRL/x indicates that you 
must press the key labeled CTRL while you 
simultaneously press another key, for example, 
CTRL/C, CTRL/Y, CTRL/O. 

Command examples show all output lines or 
prompting characters that the system prints 
or displays in black letters. All user-entered 
commands are shown in red letters. 

Vertical series of periods, or ellipsis, mean 
either that not all the data that the system 
would display in response to the particular 
command is shown or that not all the data a 
user would enter is shown. 

Horizontal ellipsis indicates that additional 
parameters, values, or information can be 
entered. 

Square brackets indicate that the enclosed item 
is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a 
file specification or in the syntax of a substring 
specification in a DCL assignment statement.) 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe ( 7 ) is used to refer to a single 
quotation mark. 
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Convention 

lowercase letters and words 


uppercase letters and words 


Meaning 

Lowercase letters and words used in format 
statements in this manual represent information 
that you must supply. Such lowercase 
information may contain hyphens for readability. 
The accompanying text defines the information 
to be supplied. For example: 

window-size 
address 


Uppercase letters and words, equal signs ( = ), 
angle brackets ( <> ), and dollar signs ($), 
must be coded as shown. For example: 

RAT=<BLK,CR> 

$OPEN 


Information enclosed within braces indicates 
that you may choose any one of the enclosed 
values. For example: 


RFM={ 


FIX 

STM 

STMCR 

STMLF 

UDF 

VAR 

VFC 
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Convention 

Meaning 

[] 

Arguments enclosed within square brackets are 
optional, but if an optional argument other than 
a trailing optional argument is omitted, you must 
include a placeholder for the omitted argument. 
This rule is shown syntactically below: 

$OPEN INFAB [.[ERR] [,SUC]] 

If you use either or both of the optional 
arguments, you must include the comma 
shown in the outside set of brackets. This 
comma acts as a delimiter between the first and 
second arguments when you use the second 
argument. When you omit the second argument 
and use the third argument, this comma acts as 
a placeholder for the omitted argument. If you 
do not use either of the optional arguments, you 
may omit this comma. 

Here is an example of an instant where the first 
optional argument is used and the second is 
omitted: 

$0PEN INFAB,ERR 

Here is an example of an instant where the 
second optional argument is used and the first 
is omitted: 

$0PEN INFAB..SUC 

Here is an example of an instant where only the 
required argument is used: 

$0PEN INFAB 
















New and Changed Features 


• VAX/VMS Version 4.4 lets you define descending keys for index files by 
using one of the 8 new key types (see Section 11), each of which is a 
descending variant of the ascending key types: 


Type of Descending Key 

XAB$B_DTP Value 

FDL Equivalent 

Unsigned 2-byte binary 

XAB$C_DBN2 

DBIN2 

Unsigned 4-byte binary 

XAB$C_DBN4 

DBIN4 

Unsigned 8-byte binary 

XAB$C_DBN8 

DBIN8 

Signed 2-byte integer 

XAB$C_DIN2 

DINT2 

Signed 4-byte integer 

XAB$C_DIN4 

DINT4 

Signed 8-byte integer 

XAB$C_DIN8 

DINT8 

Packed decimal string 

XAB$C_DPAC 

DDECIMAL 

Left-justified string of 
unsigned, 8-bit bytes 

XAB$C_DSTG 

DSTRING 


You may use the new key data types in the same manner as the original 
key data types and for all combinations of primary and alternate keys. 

In some instances, you may wish to define two keys for the same record 
field, one ascending type and one descending type. This permits you to 
process records sequentially in either forward or reverse order, except for 
duplicate key values as described in Section 7.15. 

See Section 7.19 for descriptions of how the key search options apply to 
descending keys. 

• Under VAX/VMS Version 4.4, VAX RMS supports full file sharing, record 
locking and the use of global buffers for all sequential files. Prior to 
VAX/VMS Version 4.4, this capability was restricted to sequential files 
with fixed-length, 512-byte records. 

In addition, the connect at end of file option has been enhanced for 
shared sequential files only. With VMS Version 4.4, the user program 
is able to maintain the next record position at the current end of file for 
sequential $PUT operations, irrespective of the positioning done by other 
processes sharing the file. 

For example, assume that user A invokes the Put service to write some 
data at VBN 1, offset 100, and user B moves the current end of file to 
VBN 2, offset 300 before user A puts the next record in the file. Under 
VAX/VMS Version 4.4, user A can indicate to VAX RMS that the next 
record should be written to the current end of file, position VBN 2, offset 
300. 

This capability is used typically to log events to a shared central file. 
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PART I General Information About VAX 
Record Management Services 


Part I introduces the reader to general mechanisms and conventions 
associated with VAX Record Management Services (VAX RMS). It 
discusses the following topics: 

• Argument passing 

• Control blocks 

• Symbols defined by VAX RMS 

• Invoking VAX RMS services 

• VAX RMS Macros used by VAX MACRO programs 

• Syntax conventions for VAX MACRO 

• Example programs in VAX MACRO. 
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Introduction to VAX RMS 


This section presents an overview of the general functions available through 
the use of the VAX Record Management Services (VAX RMS). It also briefly 
describes the different types of VAX RMS services and control blocks. Unless 
otherwise stated, the term RMS refers to VAX RMS. 


1.1 VAX RMS Functions 

VAX RMS is a set of generalized services that assist user programs in 
processing and managing files and their contents. These services can be 
invoked by VAX MACRO programs by using the corresponding macros 
supplied in the system library SYS$LIBRARY:STARLET.MLB. (This library is 
automatically searched for unresolved references when you assemble a source 
program.) Other VAX languages may support a similar means of invoking 
VAX RMS services. 

Although VAX RMS supports unit-record devices, such as terminals and 
printers, it is designed primarily to provide a comprehensive software 
interface to mass-storage devices, such as disk and magnetic tape drives. 

VAX RMS provides a variety of disk file organizations, record formats, and 
record access modes from which you can select the processing techniques best 
suited to your application. VAX RMS supports the sequential, relative, and 
indexed file organizations and fixed-length and variable-length record formats 
are supported for each file organization. (Relative and sequential files also 
support other record formats.) The VAX RMS record access modes permit you 
to access records within these files sequentially, directly by key value, directly 
by relative record number, or directly by record file address (RFA). VAX RMS 
also provides a means of performing block I/O operations to support users 
with certain performance-critical applications (such applications may require 
user-defined file organizations and/or record formats). 

VAX RMS ensures safe and efficient file sharing by providing: 

• Multiple file access modes, to allow file sharing to be consistent with the 
type of file operations to be performed 

• Automatic record locking in applicable file access modes, to ensure data 
integrity during record updates 

• Optional buffer sharing by multiple processes accessing the same file, to 
minimize disk access by eliminating needless I/O 

VAX RMS also enforces the security requirements of a multiuser system with 
potential multinode access by restricting file access to one or more user UIC 
types and to a list of user names. 

For systems that support DECnet network capabilities, VAX RMS provides 
a subset of file and record management services through the Data Access 
Protocol (DAP) to remote network nodes. Network DAP remote file 
operations are generally transparent to user programs. 
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1.2 Passing Arguments to VAX RMS 

The flexibility inherent in VAX RMS would require user programs to pass a 
multitude of arguments to perform such common operations as file creation 
and access. To eliminate the potential problems associated with passing 
numerous arguments for each service call, the user program places the 
arguments in one or more data control blocks before any VAX RMS service 
is invoked. The only argument required to invoke most VAX RMS services is 
the symbolic address of the appropriate data control block. 


1.2.1 VAX RMS Services and Control Blocks 

Because VAX RMS operates on files and records, services generally fall into 

one of two groups: 

• File services that create and access a new file, access (open) an existing 
file, extend the disk space allocated to a file, close a file, obtain file 
characteristics, and perform other functions related to files. 

• Record services that get, find (locate), put (insert), update, and delete 
records, and perform other operations not directly related with record 
I/O, such as associating one or more record streams (methods of accessing 
records) with an open file. 

To support the two types of service operations, VAX RMS provides two types 

of control blocks: 

• Control blocks that provide file-related arguments to VAX RMS file 
services 

• Control blocks that provide record-related arguments to VAX RMS record 
services 


1.2.2 Control Blocks for File Services 

File services use a control block called the file access block (FAB). When 
creating a file, the user must store arguments in the FAB that define the 
various file characteristics, the file specification, and certain run-time access 
options. When opening an existing file, the FAB specifies only the file 
specification and the run-time access options. 

There are three categories of FAB arguments and the following list briefly 
introduces each: 

• File specification arguments identify primary and default file 
specifications used at run-time to locate the file. 

• File characteristics arguments specify the file organization, record type, 
allocation information, and other information. 

• Run-time access options that relate to the type of operations that will be 
performed by this process and will be allowed by other processes sharing 
the file, a variety of file processing options, and the address (or addresses) 
of one or more control blocks whose fields supplement or supersede the 
information in the FAB. 
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The two types of optional control blocks that can supplement or supersede 
the information in the FAB are the name block (NAM), and the extended 
attribute block (XAB). 

The NAM block supplements the file specification information available in 
a FAB. It is especially useful for opening and locating files when the file 
specification is entered by a terminal user or when a wildcard character or a 
search list logical name is present in a file specification, representing multiple 
files. 

There is only one type of NAM block, and usually only one NAM block 
is associated with each file. To provide an extra level of defaults for a file 
specification, however, VAX RMS will apply defaults using additional NAM 
blocks that contain the file specifications of related files. 

A XAB usually supersedes and supplements the file characteristics specified 
in the associated FAB and multiple XABs may be used to support a single 
file. There are several types of XABs, each of which is used for a different 
purpose. Each type of XAB has a 6-letter mnemonic name consisting of 
the prefix "XAB" followed by a 3-letter mnemonic that relates to the XAB 
function. For instance, the XAB that supplements and supersedes the file 
allocation information in the FAB is called an allocation control XAB, or 
XABALL. 

The XABs provided by VAX RMS for file operations are listed below. 

• Allocation control XAB (XABALL) allows greater control over disk file 
allocation and positioning during file allocation. 

• Date and time XAB (XABDAT) specifies date-time values for backup, 
creation, expiration, and revision times, and the revision number. 

• File header characteristic XAB (XABFHC) receives the information 
contained in the header block of a file, which consists of certain file 
characteristics. 

• Key definition XAB (XABKEY) defines the key characteristics to be 
associated with an indexed file. 

• File protection XAB (XABPRO) defines file protection characteristics that 
specify what class of users or list of users can have certain specified access 
rights. For ANSI magnetic tape files using HDR1 labels, this XAB specifies 
the accessibility field character. 

• Revision date and time XAB (XABRDT) specifies the revision date-time 
value and the revision number to be associated with a file. 

• Summary XAB (XABSUM) stores additional file characteristics associated 
with an indexed file. 
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1.2.3 Control Blocks for Record Services 

Record services use a control block known as the record access block , or RAB. 
Some of the arguments the user must store in the RAB include the address of 
the related FAB, the address of input and output record buffers, the type and 
size of general I/O buffers, whether a file's records will be accessed directly 
or sequentially, certain tuning options, and other information. 

An extended attribute block (XAB) can both supersede and supplement the 
record characteristics specified in the RAB. As with a XAB that supersedes 
and supplements a FAB, a XAB that supersedes and supplements a RAB has 
a 6-letter mnemonic name consisting of the prefix "XAB" followed by three 
letters. Note however that there is only one XAB type for record operations, 
the terminal XAB (XABTRM) that specifies terminal input. The XABTRM 
defines the symbolic address and length of a user-supplied argument list 
that defines the terminal operation. This method of defining terminal input 
operations provides more flexibility than using RAB fields. 


1.2.4 The Dual Purpose of Control Blocks 

Control blocks not only provide input to VAX RMS services; they may also 
derive output from VAX RMS services including the following run-time 
information: 

• Detailed file characteristics, including file organization, record format, and 
record size 

• Device characteristics 

• File, directory, and device identifiers 

• The address (location) and length of a requested record 

• Returned condition values 

For this reason, certain programs specifically allocate a NAM block or one 
or more XABs dedicated to receiving information returned by VAX RMS 
services. Typically, such information can be examined to determine how the 
file should be processed. In most cases, however, control blocks are used 
both to transmit and to receive information between the user program and 
VAX RMS and should not be located in a read-only program section. 

Be sure that control block fields not currently used by a particular service have 
valid default values because future versions of VAX RMS may support those 
fields. This applies also to control block fields that are currently described 
as "ignored for DECnet operations" because future versions of VAX RMS or 
DECnet may support those fields. 
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2 The Program Interface with VAX RMS 


This section introduces the user program interface with VAX RMS that is 
applicable to all VAX languages in terms of the following: 

• The VAX RMS run-time processing environment 

• VAX RMS symbol-naming conventions 

• The calling sequence for VAX RMS services 

• Allowable program execution modes 

• Condition values returned by VAX RMS services. 


2.1 The Run-Time Environment and VAX RMS Programming 

The VAX RMS run-time processing environment consists of a set of user 
control blocks and the run-time services. The control block fields accessed by 
each service specify to VAX RMS the appropriate file and record operations. 
Depending on the operation, VAX RMS uses one or more control blocks by 
referring to one or more fields as input to, or output from, the operation. 

To use VAX RMS, you must do the following: 

1 Allocate the appropriate control block, usually at assembly-time or 
compilation-time. Control blocks must not reside in read-only storage 
and should be aligned on a longword boundary to maximize efficiency. 

2 Having allocated the control block, insert the appropriate values into the 
control block fields before you invoke the related service. 

3 Invoke the appropriate VAX RMS service. As part of this step, a condition 
value should always be examined. 

To perform advanced VAX RMS functions, you may need to set various 
control block field values at run-time between the time file is opened and 
when the VAX RMS service is invoked. 

Note that VAX languages perform some of these steps transparently when a 
particular language statement or macro is present in a source program. 

Two fields in each control block, the block length (BLN) field and the block 
identifier (BID) (or block code (COD) field in a XAB), define the length of 
the control block (in bytes) and identify the control block type, respectively. 
These internal VAX RMS fields are always used as input arguments by the 
VAX RMS service that accesses the control block and must be set before 
the control block can be used. The fields are initialized automatically by 
the appropriate VAX MACRO assembly-time initialization macro and must 
contain the correct value for the type of control block. After the block length 
and block identifier fields are established, you must treat them as read-only 
fields until the control block is no longer needed. 

Part II describes each control block field in detail, including its length and its 
symbolic name. 
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Appendix B lists the VAX MACRO calling format for each VAX MACRO 
control block macro. 

Part III lists the calling format for each service and lists the various input and 
output control block field appropriate to each service. 


2.2 Conventions for Naming Fields 

VAX RMS uses mnemonic names to identify each field in a control block. For 
example, the mnemonic name for the FAB allocation quantity field is ALQ. 

The mnemonic name (usually three characters in length) serves as a suffix to 
a symbolic name that identifies the location of each control block field. You 
should use the symbolic names to be sure you place values in the correct 
control block fields. VAX RMS defines each symbolic name as a constant 
value equal to the offset, in bytes, from the beginning of the control block to 
the beginning of the field. These field names are thus called symbolic offsets. 

Symbolic offset names are defined when the appropriate VAX MACRO control 
block initialization macro is used, when the appropriate VAX MACRO control 
block symbol definition macro is used, and also by certain VAX languages. 
Alternatively, all control block symbolic offset names are available when 
you use the VAX MACRO $RMSDEF macro in a VAX MACRO program or 
procedure. 

The format of symbolic offsets consists of a 3-letter control block identifier 
(FAB, NAM, XAB, or RAB), a dollar sign ($), a 1-letter indicator of the length 
of the field (B, W, L, Q, or T), an underscore (_), and the field mnemonic, 
which is usually three letters. 

The general format of the symbolic offset is as follows: 

ccc$x_fff 

The components of this format are summarized below. 
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Component 

Length 

Description 

ccc 

3 letters 

Identifies the type of control block: 
FAB, NAM, XAB (for all XABs), 
and RAB 

$ 

1 character 

Separates the control block 
identifier from the field length 
identifier; a dollar sign ($) 

x 

1 letter 

Identifies the length of the field: 

B for byte, W for word, L for 
longword, Q for quadword, T for 
text buffer address. See text for 
exceptions 

— 

1 character 

Separates the field length identifier 
from the field name; always an 
underscore (_) 

fff 

3 or more letters 

Identifies the mnemonic name 
of the field, which is used in the 
VAX MACRO control block macro. 
Some mnemonics contain more 
than three letters; for example, 
symbolic offset XAB$B_PROLOG 
(from XABKEY). 


For example, the FAB field whose mnemonic is ALQ has a length of one 
longword and is identified by the symbolic offset FAB$L__ALQ. The field 
NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its 
name, the related file field. 

Exceptions to the length designation are NAM$W_DID, NAM$W_FID, 
XAB$W_RFI, and RAB$W_RFA. These symbolic offsets mark the location of 
fields that are three words in length, not one word in length. 

The length of a T field is specified by the corresponding S field; for example, 
the length of the NAM$T_DVI field is specified by the symbolic value field 
named NAM$S__DVI. 

When a control block field contains options identified by bits, each valid bit 
location has a symbolic offset name. Certain control block fields are binary 
options fields consisting of bit values. For these bits in a binary options field, 
the format of symbolic names resembles the format of the field names, except 
for the length indicator. Instead of identifying the field length, which is 
always one bit, the length field indicates whether a mask value (M) or bit 
offset (V) is defined by the symbolic name, as described below. 


Format 

Description 

xxx$M_fff 

Indicates a mask value in a binary options field, typically where 
multiple bit options can be chosen. Used to set or clear bit 
values. 

xxx$V_fff 

Indicates the symbolic bit offset (number of bits from the 
beginning of the binary options field). Used to test bit values or 
to set bit values. 


The xxx identifies the control block (FAB, NAM, XAB, or RAB); the $ and _ 
are separator characters, and the fff defines the mnemonic for the bit option. 
For example, the option CTG in the FAB file-processing options (FOP) field 
has a symbolic bit offset of FAB$V_CTG and a mask value of FAB$M_CTG. 
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Another type of field can contain only certain values, thus there are no mask 
values or symbolic bit offsets. Unlike a binary options field, each possible 
value is identified by a symbolic constant value, in the following form: 

xxx$C_f« 

Note that the letter C replaces the letter M, denoting that this field is a 
constant (keyword) value field, not a mask value field. Otherwise, the 
naming convention is the same. For example, the file organization (ORG) 
field of the FAB (FAB$B_ORG) can only contain the values FAB$C_IDX 
(indexed), FAB$C_REL (relative), or FAB$C_SEQ (sequential). 

When specifying control block field locations, avoid using actual byte 
displacement values to identify control block field locations; instead, use 
the supplied symbolic offsets. VAX RMS control block field locations may 
not always be the same from release to release of VAX/VMS; however, the 
symbolic offset names that identify the field locations always identify the 
same field. 


The VAX RMS Calling Sequence 

VAX RMS uses the standard VAX calling sequence and conventions, and 
preserves all general registers across a call, except for Register 0 (RO) and 
Register 1 (Rl). When the service completes execution, it returns control to 
the calling program, passing a condition value in RO. You should analyze 
the completion value to determine the success or failure of the service and to 
alter the flow of execution of your program, if necessary. Where applicable, 
you should use the STS field and the STV field of the appropriate control 
block for signaling errors, instead of RO. For additional information about 
VAX RMS completion values, see Section 2.4. 


When calling a VAX RMS service, you must provide an argument list to 
specify the associated control block (FAB or RAB) and, optionally, any 
completion routines. The argument list is from two to four longwords in 
length, as shown in Figure 2-1. (The Rename service, however, uses a 
5-longword argument list.) 

Figure 2-1 Argument List Format 


31 


8 

7 0 

: -reserved ./ 

argument count 

control block address 

1 

error completion routine address 



i 

I 

i 

i 

success completion routine address 




optional 


ZK-875-82 


VAX RMS interprets the fields in the argument list as follows: 
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• The argument count field contains a binary value, from 1 through 3, 
representing the number of arguments in the argument list. For the 
Rename service only, set this value to 4. 

• The control block address field contains the address of either the FAB (for 
file operations) or the RAB (for record operations). 

• The error completion routine address field optionally contains the address 
of the entry mask of a user-written completion routine to be called if the 
requested operation fails. If used, the completion routine executes as an 
asynchronous system trap (AST). 

• The success completion routine address field optionally contains the 
address of the entry mask of a user-written completion routine to be called 
if the requested operation completes successfully. If used, the completion 
routine executes as an asynchronous system trap (AST). 

• The new FAB address field contains the address of the FAB that contains 
the new file name for the Rename service. This field must be present only 
for the Rename service. 


2.4 Condition Values 

Before returning to your program from a file or record operation, VAX RMS 
indicates the success or failure of the operation by setting a condition value in 
the completion status code field (STS) of the associated control block (FAB or 
RAB). 

When first returning to your program after a call to an operation, VAX 
RMS also sets general register 0 to the value in the status code field. In 
asynchronous operations. Register 0 may simply indicate that the operation 
has been initiated. 

In general, you may receive one of many error or success codes from an 
operation. (The discussion of each VAX RMS service in Part III includes a list 
of the possible condition values that you can receive.) (See Appendix A for a 
complete list of all VAX RMS status codes.) You should thus test for success 
by checking only the low-order bit of the status code for a true condition 
(bit is set). The three low-order bits returned in the status code indicate the 
severity of the code. The severity codes are as follows: 

001 (1 ) Success (low-order bit set). 

011 (3) Information (low-order bit set). 

000 (0) Warning; indicates a nonstandard condition. The operation may 
have performed some, but not all, of the requested function. 

010 (2) Error; you must recognize that a problem exists and provide a 
contingency plan in your program for such a condition. 

100 (4) Severe error; normally caused by program logic errors or other 
unrecoverable condition. 

The normal method of testing the completion status is to examine Register 
0 for success, failure, or specific completion values. For certain completion 
values, VAX RMS returns additional information in the status value field 
(STV) of the control block. The description of the codes in Appendix A 
indicates the instances when the STV contains such information. 
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When signaling VAX RMS errors, both the STS and STV fields of the 
appropriate structure (FAB or RAB) should be supplied. Doing so will 
cause all relevant information to be displayed in the error message text, 
including additional information regarding the error status in the STV field. 
For the file processing and file naming services, use the STS and STV fields 
of the specified FAB (use the old FAB for the Rename service). For record 
processing and block I/O processing services, use the STS and STV fields of 
the corresponding RAB. (Consult Table 2-2 if you are not sure which group a 
particular VAX RMS service belongs in.) 

The recommended way to signal VAX RMS errors is to provide both the STS 
and STV fields of the RAB or FAB as arguments to the Run-Time Library 
(RTL) routine LIB$SIGNAL (or LIB$STOP). Certain VAX languages provide 
a built-in means of signaling errors, such as by providing a system-defined 
function. For a more detailed explanation of condition signaling and invoking 
RTL routines, see the VAX/VMS Run-Time Library Routines Reference Manual. 

VAX RMS services are considered system services for the purpose of 
generating system service exceptions on errors. You can choose whether 
to test and handle errors in your program or set the system service failure 
exception mode (using the Set System Failure Exception Mode system service, 
SYS$SETSFM) to have failures automatically signaled. For most applications, 
especially if a high-level language is used, testing and handling errors in 
your program are the preferred method. If you test for error conditions in 
your program, you should be sure to disable any unwanted system service 
exception generation. 

Note that if the FAB or RAB is invalid or inaccessible, then the error 
completion routine will not attempt to store the error code in the STS 
field of an invalid control block structure. The following errors can be 
detected only by testing RO (or by enabling system service failure exception 
mode), following the completion of a VAX RMS operation (even if an error 
completion AST has been specified): 


RMS$_BLN 

RMS$_BUSY 

RMS$_FAB 

RMS$_RAB 

RMSS—STR 


Invalid block length field (either FAB or RAB) 

User structure (FAB/RAB) still in use 

FAB not writeable or invalid block ID field 

RAB not writeable or invalid block ID field 

User structure (FAB/RAB) became invalid during operation 


These completion codes indicate that the FAB or RAB is invalid or 
inaccessible. These completion codes can only be detected and signaled 
using RO, but are usually rare and, if they occur at all, would most likely 
occur during initial program debugging and testing. Thus, you must examine 
the completion value in RO (instead of the STS field of the FAB or RAB) for 
the completion codes listed above. If necessary, your program could test for 
these errors and, if encountered, signal these completion values using RO 
instead of the STS and STV fields. 
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2.5 Allowable Program Execution Modes 

Generally, VAX RMS executes in either executive mode or executive AST 
mode. When a VAX RMS operation is initiated, processing begins in 
executive mode. If device I/O is necessary to process the request, the $QIO 
system service is called. VAX RMS specifies an executive mode AST to signal 
completion. At this point, VAX RMS will exit from executive mode. If the 
operation is being performed asynchronously, control is returned to the caller; 
if the operation is synchronous, VAX RMS waits for an event flag in the 
access mode of the caller. When the I/O is complete, VAX RMS will continue 
processing in executive AST mode. Thus, user-mode ASTs can be serviced 
while a synchronous VAX RMS operation called from user-mode is awaiting 
I/O completion. However, processing in user mode during an asynchronous 
VAX RMS operation will be interrupted by VAX RMS processing in executive 
AST mode when I/O completes. 

VAX RMS should not be called from kernel mode, from executive-AST mode, 
nor executive mode when executive-mode ASTs are disabled. 


2.6 Reserved Event Flags 

VAX RMS uses certain system-reserved process event flags to synchronize 
its internal operations. VAX RMS reserves event flags 27, 28, 29, and 30 for 
possible use; in addition, event flag 31 is used to specify a "do not care" event 
flag for asynchronous processing. 


2.7 DIGITAL Multinational Character Set 

You can use any character in the DIGITAL Multinational Character Set in 
VAX RMS records, including the key value of an indexed file. Keys are 
collated according to their corresponding character code value. 

For a list of characters in the DIGITAL Multinational Character Set, see the 
VAX/VMS DCL Dictionary, 
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VAX RMS Macros and VAX Macro 
Programming 


This section describes the types of VAX MACRO macros. It begins with a 
description of each of the four types of macros, naming conventions and 
applicable syntax rules. The second part of the section deals with using 
macros and includes examples for each of the four types. Note that in the 
remainder of Part I, the use of the term "macro" refers to a program macro 
written in VAX MACRO. 



3.1 





VAX RMS Macros 

VAX RMS provides four types of macros used by VAX MACRO programs 

implementing VAX RMS features. The functions these macros provide are 

described below. 

• Control block initialization macros initialize a control block at assembly 
time. This type of macro performs five separate actions: 

— Allocates space within the program image for the specified control 
block 

— Defines the symbolic names associated with a control block 

— Initializes certain control block fields with internally used values 

— Initializes specified control block fields with user-specified values 

— Initializes certain fields with system-supplied defaults (does not apply 
to all control block macros) 

As an alternative to using this type of macro, a user program would have 
to allocate each control block needed with its correct length, initialize the 
internally used fields with the correct values, and initialize or set user- 
specified values in the appropriate fields. It is strongly recommended that 
the supplied macros be used for VAX MACRO programs. 

• Control block symbol definition macros define control block symbolic 
names at assembly time without allocating and initializing the control 
block. These macros are needed only when the corresponding 
initialization macro is not used and the symbols are not defined by 
the VAX language used. 

• Control block store macros set (or reset) specified fields in a control block 
with user-specified values at run time. Alternatively, you can set values 
in control block fields at run time using VAX MACRO instructions, such 
as the MOVx and MOVAx instructions. Field locations are made available 
using the symbolic names assigned to each control block field to represent 
the offset from the start of the control block. 

• Service macros invoke VAX RMS services at run time. When a service 
is invoked, one or more control blocks are examined for required field 
values. Values are also returned in one or more control blocks, including 
condition codes. VAX RMS services conform to the VAX calling standard 
and thus can be invoked directly from any VAX language without using 
the supplied macro, if needed. However, the appropriate control block 
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must be present with the appropriate field values set for the requested 
operation. 

VAX RMS supplies its macros in SYS$LIBRARY:STARLET.MLB for use by 
VAX MACRO programs. 


3.1.1 Conventions for Naming VAX RMS Macros 

The corresponding macro name that initializes each control block at assembly 
time consists of a dollar sign ($) followed by the name of the control block. 
Thus, the macro that initializes a FAB is called $FAB; the macro that initializes 
an XABALL is called $XABALL. 

The macros that define symbolic offsets without performing control 
block initialization contain the suffix "DEF" following the corresponding 
initialization macro name, for example, $FABDEF and $XABALLDEF. 

For the macros that set control block field values at run time, the name of the 
assembly time macro is followed by —STORE. Thus, the $FAB macro has a 
$FAB_STORE macro for setting FAB values at run time and the $XABALL 
macro has a $XABALL—STORE macro for setting XABALL values at run time. 

Table 3-1 summarizes the control blocks, their assembly time macro names, 
and their functions. 


Table 3-1 User Control Blocks 


Control Macro 

Block Names 

FAB 


$FAB 

SFABDEF 

$FAB_STORE 


NAM 


$NAM 

$NAMDEF 

$NAM_STORE 


RAB 


$RAB 

$RABDEF 


Function 

Describes a file and contains file-related 
information. 

Allocates storage for a FAB and initializes 
certain FAB fields; also defines symbolic offsets 
for a FAB. 

Defines symbolic offsets for a FAB. 

Moves specified values into a previously 
allocated and initialized FAB. 

Contains file specification information beyond 
that in the file access block. 

Allocates storage for a NAM and initializes 
certain NAM fields; also defines symbolic 
offsets for a NAM. 

Defines symbolic offsets for a NAM. 

Moves specified values into a previously 
specified and allocated NAM. 

Describes a record stream and contains record- 
related information. 

Allocates storage for a RAB and initializes 
certain RAB fields; also defines symbolic offsets 
for a RAB. 

Defines symbolic offsets for a RAB. 
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Table 3-1 (Cont.) User Control Blocks 


Control 

Macro 


Block 

Names 

Function 


$RAB_STORE 

Moves specified values into a previously 
specified and allocated RAB. 

XABxxx 1 


Contains file attribute information beyond that 
in the file access block. For XABTRM, contains 
information beyond that in the record access 
block. 


SXABxxx 

Allocates and initializes an XAB. 


$XABxxxDEF 

Defines symbolic offsets for an XABxxx. 


$XABxxx_STORE 

Moves specified values into a previously 
specified and allocated XABxxx. 

^he xxx 

is a 3-character mnemonic. 


VAX RMS services can be called from any VAX language using the VAX 
Procedure and Condition Handling standard. VAX RMS services are system 
services identified by the entry point prefix "SYS$" followed by three or 
more characters. In the corresponding VAX MACRO macro name, the "SYS" 
prefix is not used. For example, the Create service has an entry point of 
SYS$CREATE and a VAX MACRO macro name of SCREATE. A complete 
description of each service is provided in Part III. 

Table 3-2 describes the functions of each VAX RMS service, including the 
service entry point name and its corresponding VAX MACRO macro name. 


Table 3-2 VAX RMS Services 


Service Name 

Macro Name 

Description 

File Processing and File Naming Macros 


SYS$CLOSE 

SCLOSE 

Terminates file processing and 
disconnects all record streams 

SYSSCREATE 

SCREATE 

Creates and opens a new file of any 
organization 

SYSSDISPLAY 

SDISPLAY 

Returns the attributes of an open file 
to the user program 

SYSSENTER 1 

SENTER 

Enters a file name into a directory 

SYSSERASE 

SERASE 

Deletes a file and removes its 
directory entry 

SYS$EXTEND 

SEXTEND 

Extends the allocated space of a file 

SYSSOPEN 

SOPEN 

Opens an existing file and initiates 
file processing 


^his service is not supported for DECnet operations involving remote file access 
between two VAX/VMS systems. 
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Table 3-2 (Cont.) VAX RMS Services 


Service Name 

Macro Name 

Description 

File Processing and File Naming Macros 

SVSSPARSE 

SPARSE 

Parses a file specification 

SYSSREMOVE 1 

SREMOVE 

Removes a file name from a directory 

SYSSRENAME 

SRENAME 

Assigns a new name to (renames) a 
file 

SYSSSEARCH 

SSEARCH 

Searches a directory, or possibly 
multiple directories, for a file name 

Record Processing Macros 

SYSSCONNECT 

SCONNECT 

Establishes a record stream by 
associating a RAB with an open file 

SYS$DELETE 

SDELETE 

Deletes a record from a relative or 
indexed file 

SYSSDISCONNECT 

SDISCONNECT 

Terminates a record stream by 
disconnecting a RAB from an open 
file 

SYS$FIND 

SFIND 

Locates and positions to a record 
and returns its RFA 

SYSSFLUSH 

SFLUSH 

Writes (flushes) modified I/O buffers 
and file attributes 

SYSSFREE 

SFREE 

Unlocks all records previously locked 
by the record stream 

SYS$GET 

SGET 

Retrieves a record from a file 

SYSSNXTVOL 1 

SNXTVOL 

Causes processing of a magnetic 
tape file to continue to the next 
volume of a volume set 

SYSSPUT 

SPUT 

Writes a new record to a file 

SYS$RELEASE 

SRELEASE 

Unlocks a record pointed to by the 
contents of the RAB$W_RFA field 

SYSSREWIND 

SREWIND 

Positions to the first record of a file 

SYSSTRUNCATE 

STRUNCATE 

Truncates a sequential file 

SYS$UPDATE 

SUPDATE 

Rewrites (updates) an existing record 
in a file 

SYSSWAIT 

SWAIT 

Awaits the completion of an 
asynchronous record operation 


1_ This service is not supported for DECnet operations involving remote file access 
between two VAX/VMS systems. 
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Table 3-2 (Cont.) VAX RMS Services 


Service Name 

Macro Name 

Description 

Block I/O Processing Macros 

SYSSREAD 

$READ 

Retrieves a specified number of 
bytes from a file, beginning on block 
boundaries 

SYS$SPACE 

$SPACE 

Positions forward or backward in a 
file to a block boundary 

SYSSWRITE 

SWRITE 

Writes a specified number of 
bytes to a file, beginning on block 
boundaries 


3.1.2 Applicable VAX Macro Syntax Rules 

One of the conventions of VAX RMS control block macros is to use the 
mnemonic names associated with each field as keywords to identify each 
argument. The mnemonic keywords allow the arguments they identify to be 
coded in any order and ensure the accuracy of argument value placement. 

For example, the mnemonic keyword for the field in the FAB that contains 
the allocation quantity is ALQ. Thus, when using the $FAB macro to initialize 
the allocation quantity field, the following macro expression might be used: 

INFAB: $FAB ALQ=500 

This macro statement defines the start of the FAB at label (symbolic address) 
INFAB and initializes the allocation field (at symbolic offset ALQ) to provide 
500 blocks of space to the file being created. 

In this instance, if you want to change the allocation value to 250 blocks at 
run time, you could use the following macro instruction: 

MOVL #250, INFAB+FAB$L_ALQ ; Set allocation quantity 

In fields that contain binary options or keyword values, you should use the 
appropriate keyword or symbolic binary option value. For example, the FAB 
has a field at symbolic offset ORG that specifies the file organization. Three 
keywords are defined for this field; SEQ (sequential file), REL (relative file) 
and IDX (indexed file). To specify an indexed file organization, you should 
use the following macro expression: 

OUTFAB: $FAB 0RG=IDX 

To set this value at run time, you must move the formal title of the value into 
the formal title of the field: 

MOVAL OUTFAB, R5 ; Move address into R5 

MOVB #FAB$C_IDX, FAB$B_0RG(R5) ; Store constant value 

In control block macros, arguments for bit fields that can contain multiple 
values are usually delimited by the less than ( <) and the greater than (> ) 
characters. Consider the file access (FAC) field in the FAB (FAB$B_FAC), a 
bit field that can contain multiple values. To permit a process to do get and 
put operations, the following macro expression could be used: 

INFAB: $FAB FAC=<GET,PUT> ; Specify Put and Get operations 
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Control block macro arguments that contain values that are to be interpreted 
as ASCII characters (such as a file specification) are similarly delimited by 
the less than ( <) and the greater than (> ) signs. The use of the < and 
> delimiters is noted in the format and argument description of the control 
block macros in Part II. 

At run time, to test the FAB$B_FAC field if GET file access is currently 
allowed and to set it if it is not allowed, the VAX MACRO instructions BBS 
and BISB might be used: 

MOVAL OUTFAB, R6 ; Move addr into R6 

BBS #FAB$V_GET, FAB$B_FAC(R6), OK ; Branch i 1 set 

BISB #FAB$M_GET, FAB$B_FAC(R6) ; Set if not set 

OK: ; Complete operation 

In programming with VAX RMS macros, you follow the same coding rules 
used by the VAX MACRO assembler. These rules are provided below for ease 
of reference. 

1 Comments must be separated from the rest of the code line by a semicolon 
(;). For example: 

$FAB BKS-4 ; Bucket size 

2 All the arguments for a macro must be coded on a single line. If all the 

arguments needed do not fit on one line or if you do not want them on 
one line, you can type the continuation character—a hyphen (-)—as the 
last character on the line, and then continue typing arguments on the next 
line. Comments can follow the hyphen. For example: 

$FAB FNA=FLNAM,- ; Filename address 

ALQ=100,- ; Allocation quantity 

BKS=4 ; Bucket size 

3 Arguments and subarguments can be separated from each other by one of 
the following: 

• A comma, with or without spaces or tabs 

FNA=FLNAM,ALQ=100 

• A blank space 

FNA=FLNAM ALQ=100 

• Multiple blank spaces or tabs 

FNA=FLNAM ALQ=100 

The comma without a space or tab is preferred. All coding examples in 
this manual use a comma to separate arguments. 


3.2 Using the VAX RMS Macros 

This section provides examples of using the four types of VAX RMS macros. 
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3.2.1 Control Block Initialization Macros 

A major advantage to using the control block initialization macros is that 
they direct the initialization values to the correct field locations in the control 
block. Returned status values do not apply here because this type of macro 
executes at assembly time. 

The program location of a control block initialization macro defines the 
beginning of the control block. Because the address of the control block is a 
required argument for most services and for some control block macros, the 
macro name should be preceded by a symbolic address (label), such as the 
following: 

MYFAB: $FAB 

Arguments usually require an address, such as a symbolic address, or a value. 
VAX RMS initializes the appropriate field by simply taking the supplied 
argument and placing it after the appropriate macro data declaration directive, 
such as the following: 

.ADDRESS address 
.BYTE value 

There are certain fields, however, that must be treated as an ASCII character 
string or become values in a binary options field. Such fields must be 
delimited by the less than ( <) and greater than (> ) signs, under the 
following conditions: 

• When the argument is a file specification (ASCII character string) 

• When more than one argument is supplied for a binary options field, 
where each bit option is identified by a 3-letter mnemonic 

• Where otherwise indicated in the format of the macro, such as for 
UICs and file identifiers in which multiple values separated by commas 
constitute the argument 


Here are several examples: 


MYFAB: 

$FAB 

FAC=<GET, PUT>,- 
FNM=<DEGREE_DAY.DAT>,- 

; Multi-option field 
; File specification 



NXT=MYXPRO,- 
0RG=SEQ 

; XAB address 
; Single-option field 

MYXPRO: 

IXABPRO 

PRO=<RWED,RWED,R,R>,- 
UIC=<377,377> 

; File protection 
; UIC 


The complete format of each control block initialization macro is provided 
in Appendix B, showing those arguments that must be delimited by less than 
( < ) and greater than ( > ) signs. 

Because control block fields receive values during the execution of services, 
do not place the macro name in a read-only program section. For efficiency, 
you should explicitly align the control blocks on a longword boundary. The 
initialization macros display an informational message in the listing file if the 
control block is not longword aligned. 

In summary, initialization macros must be placed in a writeable data program 
section in which the data has been aligned on a longword boundary. 
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3.2.2 Control Block Symbol Definition Macros 

The control block symbol definition macros requires only the use of the 
macro name and has no arguments. Each control block symbol definition 
macro contains the suffix "DEF" following the name of the initialization 
macro, which defines all symbols associated with the named control block. 
The symbols for all control blocks can be defined by using the macro name 
$RMSDEF in a VAX MACRO program. 

The formats for the control block symbol definition macro consist entirely of 
the macro name and are not documented any further in this manual. 

These macros can be placed in a data or executable code program section. No 
value is returned in RO or any control block field. 


3.2.3 Control Block Store Macros 

The control block store macro consists of executable run-time code. Thus, the 
control block store macro must be placed within an executable code program 
section. These macros may use RO to move arguments to their respective field 
locations. Thus, RO is not preserved and does not contain a condition code. 
The only detectable errors are assembly-time errors. 

In general, the calling format of each store macro resembles the corresponding 
initialization macro. Certain arguments, however, are required or can be 
specified in the store macro that are not arguments in the corresponding 
initialization macro. Such arguments include values that usually only exist 
as run-time values, such as date-time values, file identifier values, device 
identifier values, directory identifier values, and a record's file address value. 

There are several possible differences in the format of a control block 
initialization macro and its corresponding control block store macro. 

1 The argument for the address of the FAB, NAM block, RAB, or XAB to 
receive the argument values is required. This argument can be omitted 
if the control block address is contained in RO. If this argument is not 
a register value in the form Rn, the control block address is loaded into 
RO. This argument is not present in the corresponding control block 
initialization macro. 

2 For each argument that requires an address, the store macro uses the 
VAX MACRO instruction MOVAx (usually MOVAL) to move the address 
into the appropriate control block field. Thus, VAX MACRO expressions 
can be used. For instance, you can use a symbolic address to specify 
the control block address argument directly (for example, FAB=MYFAB, 
NAM=MYNAM, RAB=MYRAB, or XAB=MYXAB). 

You may also specify a register that contains the address using the form 
Rn, where n is a number from 0 through 12. 

3 For each argument that requires a nonkeyword data value, the store 
macro uses the VAX MACRO instruction MOVx to move data into the 
appropriate control block field. Thus, VAX MACRO expressions can be 
used. Note that a number sign (#) must precede a literal nonkeyword 
value, except when a literal value is delimited by less than ( <) and 
greater than (> ) signs. However, if you specify the address where the 
argument value resides, a number sign must not precede the symbolic 
address or the register expression that contains the address. 
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4 For binary option or keyword value fields, use the supplied keyword 
without a number sign and do not use a VAX MACRO expression. 
Multiple keyword arguments must be delimited by less than ( <) and 
greater than ( > ) signs. 

Certain arguments are usually specified as run-time values using one of the 
following: 

• A VAX MACRO expression 

• The symbolic address of the argument value 

The macro format for each store macro is provided in Appendix B; exceptions 
to the general rules listed above are also described there. 

Example 3-1 illustrates the use of the $XABDAT__STORE macro to set the 
creation date of the file to a date that indicates the beginning of fiscal 
quarter, allowing the creation date to mark a valid starting date for the 
data it contains. 

Example 3-1 Use of the $XABDAT and $XABDAT_STORE 
Macros 


.TITLE CREAT - SET CREATION DATE 
; Program that uses XABDAT and XABDAT_STORE 

.PSECT LONG WRT.NOEXE 

MYFAB: $FAB ALQ=500, FOP=CBT, FAC=<PUT>, - 

FNM=<DISK$:[PROGRAM]SAMPLE.FILE.DAT>,- 

0RG=SEQ, RAT=CR, RFM=VAR, SHR=<NIL>, MRS=52, XAB=MYXDAT 


MYXDAT: 

$XABDAT 



ATIM: 

.ASCID 

/l-JUL-1985 00:00:00.00/ 


BTIM: 

.BLKQ 

1 


’ 

.PSECT 

CODE N0WRT.EXE 



.ENTRY 

CREAT, ~M<> 


START: 

$BINTIM_S TIMBUF=ATIM, TIMADR=BTIM 

Convert ASCII to binary time 


BLBC 

R0,SS_ERR 

Branch on error 


$XABDAT. 

.STORE XAB=MYXDAT, CDT=BTIM 

Move time into XAB$Q_CDT 


$CREATE FAB=MYFAB 

Create file; populate 


BLBC 

R0,ERROR 

file later 

CLOSE: 

$CL0SE 

FAB=MYFAB 

Close file 


BRB 

FINI 

and exit 

ERROR: 

PUSHL 

FAB$L_STV+MYFAB 

Push FAB STS and 


PUSHL 

FAB$L_STS+MYFAB 

STV on stack 


CALLS 

#2, G~LIB$SIGNAL 

Signal error 


BRB 

FINI 


SS_ERR: 

PUSHL 

R0 

; Push R0 


CALLS 

#1, G~LIB$SIGNAL 

; Signal error 

FINI: 

RET 




.END CREAT 


This short program creates a file with a creation date of midnight July 1, 
1985. The FAB at symbolic address MYFAB defines a sequential file with 
variable-length records up to 52 bytes in length and specifies an allocation 
size of 500 blocks using the contiguous-best-try file processing option. It also 
specifies the file specification. The .ASCID assembler directive defines the 
constant date-time character string at symbolic address ATIM. 
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The $BINTIM system service is invoked to convert the constant ASCII time at 
symbolic address ATIM to binary format in the quadword at BTIM. The BTIM 
value is moved into the XAB$Q_CDT field of the XABDAT control block at 
symbolic address MYXDAT using the following XABDAT_STORE macro: 

$XABDAT_STORE XAB=MYXDAT, CDT=BTIM 

Because the creation date in field XAB$Q_CDT is input to the Create service 
($ CREATE macro), the value must be stored prior to invoking the Create 
service. The file is created, then closed. Note that Create service errors are 
signaled using the FAB$L_STS and FAB$L_STV fields, not Register 0. 


3.2.4 Service Macros 


The general macro format of VAX RMS service macros is described 
in Part I. Part III describes each service in great detail, including the VAX 
calling format. 

Note that the general information applicable to invoking VAX RMS services 
in Section 2 also applies to programs written in VAX MACRO. 

The service macros use two generalized formats: 

1. label: macro-name 

2. label: macro-name RAB=rab-address,- 

ERR=entry,- 
SUC=entry 

The first format above takes no arguments. You supply the argument list 
within your program, and the argument pointer register (AP) is assumed to 
contain the address of the argument list. An example of this format is shown 
below. 

ARG.LOC: .BLKL 2 


MOVL #1,ARG_L0C 
MOVAL INFAB. ARG.L0C+4 
MOVAL ARG_L0C, AP 
$0PEN 


Move number of args to ARG_L0C 
Move FAB address to ARG.L0C+4 
Move ARG_L0C address to AP 
Open file 


In this form, the $OPEN macro expands to the following VAX MACRO code: 

CALLG (AP), G~SYS$0PEN 


In the second format, you supply arguments that automatically generate 
an argument list on the stack according to the values you supplied. You 
specify these arguments using keywords, which can be in any order. You 
must separate each keyword by a comma, a blank space, or tabs. The only 
argument required when using the second format is the control block address 
(FAB=fab-address or RAB=rab-address). This argument must be either a 
general register (R0 through Rll) containing the control block address, or a 
suitable address for a PUSHAL instruction. If you omit this argument, no 
other arguments are allowed; in other words, you must use the first format. 

The ERR=entry and SUC=entry arguments are optional and, if used, provide 
the addresses of completion routine entry points. Completion routines are 
always executed as ASTs. VAX RMS places the values you supply into the 
argument list on the stack during execution of the expanded macro. These 
values must be addresses that can be used by a PUSHAL instruction. 
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Here is an example of the second format: 

$OPEN FAB=INFAB 

This macro line expands to the following VAX MACRO code: 

PUSHAL INFAB 

CALLS #01. G~SYS$0PEN 

When the argument list contains a completion routine argument, an AST is 
queued. When the AST routine executes, the following conditions hold: 

• General registers RO through Rll are undefined. The AP contains the 
address of the AST argument list; the AST argument value in the AST 
argument list specifies the address of the associated control block (FAB or 
RAB). The status must be retrieved from the completion status code field 
(STS) of the associated control block. 

• Any general registers saved by an entry mask can be modified, in addition 
to RO and Rl. 

• Additional calls to VAX RMS services can be made within the completion 
routines. 

• To exit from a completion routine, you must perform any necessary 
cleanup operations and execute a RET instruction. 

The calling format of each VAX RMS service is listed alphabetically in Part III. 
For example, the format for the Close service is 

SYS$CL0SE fab [,err] [,suc] 

When using a service macro to call a service, however, remember to omit the 
"SYS" prefix and use the 3-letter keywords to identify the argument (such as 
FAB=MYFAB). 

All file-processing macros (listed in Table 3-3) have a format that requires the 
FAB address as an argument and optionally allows you to specify the entry 
points for error or success condition handlers, as shown below. 

$macro FAB=fab-addr [,ERR=error-entry] [,SUC=success-entry] 

For example, to invoke the $OPEN macro and pass it the FAB address of 
INFAB and the error entry point of OPEN—ERR, you could use the following 
macro: 

$0PEN FAB=INFAB, ERR=0PEN_ERR 

Note that the $RENAME macro has a different format, as noted in Table 3-3. 
This file processing macro has the following format: 

$RENAME 0LDFAB=old-fab-addr [,ERR=error-entry] 

[,SUC=succe8B-entry] ,NEWFAB=new-fab-addr 

As shown here, all record-processing (and block I/O) macros listed in 
Table 3-3 have a format that requires the RAB address as an argument 
and optionally allows you to specify the entry points for error or success 
condition handlers: 

$macro RAB=rab-addr [,ERR=error-entry] [,SUC=success-entry] 

Note that the $Wait macro has a different format, in that it does not use the 
error and success arguments: 

$WAIT RAB=rab-addr 
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Table 3-3 lists each service macro according to its macro type. 


Table 3-3 File, Record, and Block I/O Processing Macros 


Macro Type 

Applicable Macros 

File Processing 

SCLOSE, $CREATE, SDISPLAY, SENTER, SERASE, 
$EXTEND, SNXTVOL, $OPEN, SPARSE, SREMOVE, 
SRENAME 1 , SSEARCH 

Record Processing 

SCONNECT, SDELETE, SDISCONNECT, $FIND, 

SFLUSH, SFREE, SGET, SPUT, SRELEASE, SREWIND, 
STRUNCATE, SUPDATE, SWAIT 1 

Block I/O 

SREAD, SSPACE, SWRITE 

denotes macro with nonstandard format (see text). 


After calling a VAX RMS service, you should check the status code returned 
in RO (and the STS field of the appropriate control block). The recommended 
way to signal errors is to provide both the STS and STV fields of the FAB 
or RAB as arguments to the appropriate Run-Time Library routine. The 
following VAX MACRO instructions invoke the LIB$SIGNAL routine for a 
file-related (FAB) error using the CALLS (stack) form of calling a routine, 
where the FAB is located at symbolic address MYFAB (not shown): 


F.ERR: 


PUSHL MYFAB+FAB$L_STV 
PUSHL MYFAB+FAB$L_STS 
CALLS #2, G~LIB$SIGNAL 


Push fields on stack 
in reverse order 
Invoke signal routine 
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4 VAX RMS Example Programs 


This section includes very brief examples illustrating the implementation 
of VAX RMS at the VAX MACRO programming level. See the Guide to 
VAX/VMS File Applications for VAX RMS examples using the File Definition 
Language (FDL) utility. 

Using VAX RMS macros, you can create new files, process existing files, 
extend and delete files, and read, write, update, and delete records within 
files. 

To create and process VAX RMS files, your program must contain calls to 
appropriate VAX RMS services. Generally, you make these calls by using 
the VAX RMS service macros for run-time processing. When encountered 
at run time, the expanded code of these macros generates a call to the 
corresponding VAX RMS services. Each macro and its resultant call represent 
a program request for a VAX RMS file or record service, or a block I/O 
transfer operation. 


4.1 Creating, Accessing, and Deaccessing a File 

The Create service constructs a new file according to the attributes you 
specify in the FAB for the file whereas the Open service makes an existing 
file available for processing by your program. Both of these services, invoked 
by the $CREATE and $OPEN macros respectively, allocate resources within 
the system to establish access (a path) to a file. You must Open or Create 
a file to perform most file operations and any record operations on that file. 
Applications designed for shared access must declare the type of sharing at 
this time. The user specifies the various types of shared access by setting bits 
in the file access control (FAB$B_FAC) and share (FAB$B_SHR) fields in the 
appropriate FAB. 

VAX RMS provides several file-processing options for the Create service. 

The create-if option (FAB$L_FOP field FAB$V__CIF option) requests that the 
file be created only if it does not exist. If the file does exist in the specified 
directory, the file is opened, not created. The Open and Create services both 
establish access to the desired file, but the Create service additionally allocates 
disk space and performs functions related to allocation. 

When you are finished processing a file, you invoke the Close service 
($CLOSE macro) to close the file, disconnect all record streams associated 
with the file and free all resources allocated to the file. If you do not explicitly 
invoke the Close service when the program image exits, VAX RMS will 
attempt an implicit close. All resources associated with open files are returned 
when the files are deaccessed at image run-down time. However, process 
permanent files, which are special files that may be directly accessed only by 
privileged images, will not be implicitly closed by an image exit. 
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4.1.1 Example of Opening and Creating Files 

Example 4-1 illustrates the use of the Open, Create, Connect, Get, Put and 
Close services to access and copy records from one file to another. Note 
that the arguments to the $FAB and $RAB macros are listed vertically on 
separate lines for ease of reading them. However, the argument list must 
be contiguous and a common programming error is omission of required 
delimiters and continuation characters when the arguments are listed in this 
manner. 
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Example 4-1 Use of the Create, Open, and Close Services 


•TITLE COPYFILE 

This program copies the input file to 



.PSECT 

DATA,WRT,NOEXE 

INFAB: 

$FAB 

FNM 

= 

<INFILE:>, 



DNM 

= 

<.INV> 

INRAB: 

$RAB 

FAB 

= 

INFAB,- 



ROP 

SB 

RAH,- 



UBF 

= 

REC.BUFF,- 



USZ 

S 

REC.SIZE 

OUTFAB: 

$FAB 

FNM 

= 

<OUTFILE:> 



DNM 

s 

<.INV>,- 



FOP 

s 

CTG, - 



FAC 

= 

<PUT>,- 



SHR 

= 

<NIL>,- 



MRS 

= 

REC.SIZE,- 



RAT 

= 

CR 

OUTRAB: 

$RAB 

FAB 

= 

OUTFAB,- 



ROP 

= 

WBH, - 



RBF 

= 

REC.BUFF 


REC.SIZE = 132 
REC.BUFF: 

.BLKB REC.SIZE 

.PSECT CODE,NOWRT,EXE 
; Initialization - Open input and output 



.ENTRY 

COPYFILE,~M<R6> 


$0PEN 

FAB=INFAB 


BLBC 

R0.EXIT1 


$C0NNECT RAB=INRAB 


BLBC 

RO.EXIT2 


MOVL 

INFAB+FAB$L_ALQ,- 
OUTFAB+FAB$L_ALQ 


SCREATE FAB=OUTFAB 


BLBC 

R0.EXIT3 


ICONNECT RAB=OUTRAB 


BLBS 

RO,READ 


BRB 

EXIT4 

EXIT1: 

MOVAL 

INFAB,R6 


BRB 

F.ERR 

EXIT2: 

MOVAL 

INRAB,R6 


BRB 

R.ERR 

EXIT3: 

MOVAL 

OUTFAB,R6 


BRB 

F.ERR 

EXIT4: 

MOVAL 

OUTRAB,R6 


BRB 

R.ERR 

; Copy records 

loop 

READ: 

$GET 

RAB=INRAB 


BLBS 

RO,WRITE 


CMPL 

RO,#RMS$_EOF 


BEQL 

DONE 


BRB 

EXIT2 

WRITE: 

MOVW 

INRAB+RAB$W_RSZ, - 
OUTRAB+RAB$W_RSZ 


$PUT 

RAB=OUTRAB 


BLBC 

R0.EXIT4 


BRB 

READ 


the output file. 


; Primary input file name 
; Default input file extension 
; Pointer to FAB 
; Read-ahead option 
; Record buffer 
; and size 

; Primary output file name 
; Default output file name 
; Make contiguous file 
; Open for PUT operations 
; Exclusive file access 
; Maximum record size 
; Implied carriage control 

; Pointer to FAB 
; Write-behind option 
; Output uses same buffer 
; as input 

; Maximum record size 
; Record buffer 


files and connect streams 

No registers to save 
Open input file 
Quit on error 
Connect to input 
Quit on error 

Set proper size for output 

Create output file 
Quit on error 
Connect to output 
Branch to READ loop 
Trap error 

Error: Keep FAB address 
Signal file error 
Keep RAB address 
Signal record error 
Keep FAB address 
Signal record error 
If error, retain RAB addr. 
Signal record error 


Get a record 
Write the record 
Was error end-of-file? 
Successful completion 
Error otherwise 
Input RAB sets record 
size for output RAB 
Write the record 
Quit on error 
Go back for more 


(Continued on next page) 
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Example 4-1 (Cont.) Use of the Create, Open, and Close 

Services 


Close files, signal any errors, 


F_ERR: 

PUSHL 

FAB$L_STV(R6) 


PUSHL 

FAB$L_STS(R6) 


CALLS 

#2, G~LIB$SIGNAL 


BRB 

EXIT 

R_ERR: 

PUSHL 

RAB$L_STV(R6) 


PUSHL 

RAB$L_STS(R6) 


CALLS 

#2, G~LIB$SIGNAL 

DONE: 

$CL0SE 

FAB=INFAB 


$CL0SE 

FAB=OUTFAB 

EXIT: 

RET 



.END 

COPYFILE 


and exit 

; Push STV and STS of FAB 
; on the stack 
; Signal error 

; Push STV and STS of RAB 
; on the stack 
; Signal error 
; Close input 
; and output 

; Return with status in RO 


This example illustrates how you can use the sequential file organization to 
create a new file by copying records from an existing file. The newly-created 
file and the source file have variable-length records. 

This example assumes that an external program identified the input file as a 
search list logical name using this statement: 

$ ASSIGN [INV]30JUN85,[INV.OLD]30JUN85 INFILE: 

This dictates that VAX RMS should look for the input file in directory [INV] 
first, and if it does not find the file, it should look in directory [INV.OLD]. 

The program also specifies a default file extension value of .INV for the input 
file using this statement: 

DNM=<.INV> ; Default input file name 

Next the program configures the RAB used for the input file (labeled INRAB:). 
The first argument links the RAB to the associated FAB (INFAB:) and this is 
the only required argument to a RAB. The rest of the arguments specify the 
read-ahead option (described in later text) and the record buffer for the input 
file. 

The Get service uses the UBF field and the USZ field as inputs to specify the 
record buffer and the record size, respectively. 

The program then configures the FAB for the output file. The first argument 
uses the FNM field to equate the file name to the externally defined logical 
name OUTFILE. After the program specifies the default file specification 
extension for the output file, it specifies three additional FAB fields. 

First it specifies that VAX RMS should allocate contiguous space for the 
output file by setting the CTG bit in the FAB$L_FOP field of the FAB. 

Next the progam uses a program-defined variable to store the value 132 in 
the MRS field: 

MRS=REC_SIZE 
REC_SIZE= 132 

The program then specifies that each record is to be preceded by a line feed 
and followed by a carriage return whenever the record is output to a line 
printer or terminal: 


RAT=CR 
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Because the program reads and then alternately writes each record, the input 
file and the output file may share the same buffer. However, because the 
Put service does not have access to the UBF and UBZ fields, the output RAB 
defines the buffer using the RBF and and the RSZ fields. 

Note that the UBF, USZ, and RBF values are set prior to run time, but that 
the RSZ value is set at run time, just prior to invocation of the Put service. 
This is done because the input file contains variable length records and the 
Put service relies on the Get service to supply each record's size by way of 
the RSZ field, an INRAB output field. 

The following statement from the sample program illustrates this feature: 

WRITE: MOVW INRAB+RAB$W_RSZ, - ; Input RAB sets record 

OUTRAB+RAB$W_RSZ ; size for output RAB 

The run-time processing macros for the input file consist of a $OPEN, a 
$CONNECT, a $GET, and a $CLOSE macro. Because the input file already 
exists, the program accesses it with a $OPEN macro. The sole argument to 
this macro identifies the FAB to the Open service: 

$0PEN FAB=INFAB 

Next, the program connects a record stream to the input file by calling the 
Connect service and specifying INRAB as the appropriate RAB: 

ICONNECT RAB=INRAB 

Note that upon completion of each service call, the program tests the 
condition value in RO returned by the service before proceeding to the 
next call. If the call fails, the program exits with the appropriate control block 
address in R6. 

After creating the output file and establishing its record stream, the program 
begins a processing loop where the Get service reads a record from the input 
file and the Put service writes the record to the output file. When all file 
records are copied, as indicated by the detection of the end of the file, the 
program exits to label DONE which closes both files. 

The Close service disconnects the record stream for all RABs connected to 
the specified FAB. In a multistream environment (more than one RAB can 
be connected to a single FAB), a program may disconnect individual record 
streams using the Disconnect service. 


4.1.2 Example of Creating a Multiple-Key Indexed File 

Example 4-2 creates an indexed file on a remote DECnet node from a 
sequential file on the local node. The indexed file contains three keys. 
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Example 4-2 Use of the Create Service for an Indexed File 


.TITLE CREATEIDX - CREATE INDEXED FILE 
.IDENT /V001/ 

This program creates an indexed file with three keys from a 
sequential file containing a name and address list. The record 
format of the input file is shown below: 


First Name 

Column 

00-10 

Middle Initial 

Column 

11-11 

Last Name 

Column 

12-26 

Street 

Column 

27-46 

City 

Column 

47-58 

State 

Column 

59-60 

Zip Code 
Reserved for 

Column 

61-65 

new data 

Column 

66-end of record 


The input and output files are specified by the logical names SRC 
and DST, respectively. For example: 

$ DEFINE SRC DBB1:[TEST]INPUT.DAT 
$ DEFINE DST TRNTO::DRA4:[RMS.FILES]OUTPUT.DAT 
$ RUN CREATEIDX 


******************************************************************** 

.SBTTL Control block and buffer storage 
.PSECT DATA NOEXE.LONG 


Define the source file FAB and 

SRC_FAB: 

$FAB FAC=<GET>,- 

FOP=<SQO>,- 
FNM=<SRC:> 

SRC.RAB: 

$RAB FAB=SRC_FAB,- 

RAC-SEQ,- 
UBF=BUFFER,- 
USZ=BUFFER_SIZE 

; Define the destination file FAB 

DST.FAB: 

$FAB FAC=<PUT>,- 

F0P=CTG,- 
FAC = <PUT>,- 
SHR = <NIL>,- 
FNM=<DST: >, - 
MRS=128,- 
RFM=VAR,- 
RAT=<CR>,- 
ORG=IDX,- 
XAB=DST_KEYO 

DST.RAB: 

$RAB FAB=DST_FAB,- 
MBF=3,- 
RAC=KEY,- 
RBF=BUFFER,- 
R0P=L0A,- 
RSZ=BUFFER_SIZE 


control blocks. 


; File access for GET only 
; DAP file transfer mode 
; Name of input file 

; Address of associated FAB 
; Sequential record access 
; Buffer address 
; Buffer size 

RAB control blocks. 


File access for PUT only 
Allocate contiguous 
Open for PUT operations 
Exclusive file access 
Name of output file 
Maximum record size 
Variable length records 
Implied carriage control 
Indexed file organization 
Address of start of XAB chain 

Address of associated FAB 
Use 3 buffers 
Random record writes 
Buffer address 
Specify initial fill size 
Buffer size 


Define key definition XABs to describe the three keys. 


(Continued on next page) 
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Example 4-2 (Cont.) Use of the Create Service for an Indexed 

File 


DST_KEYO: 

$XABKEY REF=0,- 
DAN=0,- 
DFL=1536,- 
IAN=1,- 
IFL-1536,- 
PR0L0G=3.- 
P0S=<12,0,11>,- 
SIZ=<15.1.1>,- 
NXT=DST_KEY1 

DST_KEY1: 

$XABKEY REF=1,- 
DAN=2,- 
IAN=2,- 
IFL=768,- 
P0S=47,- 
SIZ=12,- 
FLG SS <CHG, DUP>, - 
NXT=DST_KEY2 

DST.KEY2: 

IXABKEY REF=2,- 
DAN=2,- 
IAN=2,- 
IFL=768,- 
P0S=59,- 
FLG=<CHG,DUP>,- 
SIZ=2,- 
NXT=DST_ALL0 

f 

; Define allocation control XABs 

• 

DST.ALLO: 

SXABALL AID=0,- 

ALQ=328,- 
A0P=<CBT>,- 
BKZ=4,- 
DEQ=112,- 
NXT=DST_ALL1 

DST.ALL1: 

SXABALL AID=1,- 
ALQ=8,- 
A0P=<CBT>,- 
BKZ=4,- 
DEQ=4,- 
NXT=DST_ALL2 

DST.ALL2: 

SXABALL AID=2,- 

ALQ=112,- 
A0P=<CBT>,- 
BKZ=2,- 
DEQ=38.- 
NXT=DST_ALL3 


; Primary key is Name 
; Key reference number 
; Define data XABALL 
; Define data fill of 75X 
; Define index XABALL 
; Initial index fill 75*/. 

; Request Prolog 3 
; Segmented key: last name, 

; first initial, middle initial 
; Address of next XAB in chain 
; 1st alternate key is City 

; Key reference number 

; Data level (SIDR) XABALL 
; Index XABALL 
; Initial index fill 75'/, 

; Starting key position 
; Key size 

; Duplicates and changes 
; Address of next XAB in chain 
; 2nd alternate key is State 

; Key reference number 

; Data level (SIDR) XABALL 
; Index XABALL 
; Initial index fill 757, 

; Starting key position 
; Duplicates and changes 
; Key size 

; Designate next XAB 
define multiple areas 


Data area definition 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Primary key index area 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Alternate key data area 
Allocation quantity and 
contiguous best try 
Bucket size of 2 blocks 
Default extension quantity 
Designate next XAB 


(Continued on next page) 
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Example 4-2 (Cont.) Use of the Create Service for an Indexed 

File 


Allocate buffer to the size of the largest record that will be read. 


BUFFER: .BLKB 66 

BUFFER.SIZE=.-BUFFER 


; Buffer for input and output 
; Buffer size 


;********************************************************************* 
.SBTTL Mainline 

.PSECT CODE NOWRT.BYTE 


Start of program 

.ENTRY CREATEIDX,~M<R6> 

Open the source and destination files. 


; Entry point 



$0PEN 

FAB=SRC_FAB 

Open input file 


BLBC 

RO.EXITl 

Branch on failure 


ICONNECT RAB=SRC_RAB 

Connect input record stream 


BLBC 

R0.EXIT2 

Branch on failure 


$CREATE 

FAB=DST_FAB 

Create output file 


BLBC 

R0.EXIT3 

Branch on failure 


ICONNECT RAB=DST_RAB 

Connect output record stream 


BLBC 

R0.EXIT4 

Branch on failure 


BRB 

LOOP 

Bypass signaling code 

EXITl: 

MOVAL 

SRC_FAB,R6 

Keep FAB address 


BRB 

F_ERR 

Signal error 

EXIT2: 

MOVAL 

SRC.RAB.R6 

Keep RAB address 


BRB 

R.ERR 

Signal error 

EXIT3: 

MOVAL 

DST_FAB,R6 

Keep FAB address 


BRB 

F_ERR 

Signal error 

EXIT4: 

MOVAL 

DST.RAB,R6 

Keep RAB address 


BRB 

R.ERR 

Signal error 

; Transfer records until end-of-file is 

reached. 

LOOP: 

IGET 

RAB=SRC_RAB 

Read next rec from input file 


BLBS 

RO.PUT 

Branch on success 


CMPL 

RO,#RMS$_EOF 

Was it end-of-file (EOF)? 


BNEQ 

EXIT2 

Branch if not EOF error 


BRB 

CLOSE 

Close and exit if EOF 

PUT: 

$PUT 

RAB=DST_RAB 

Write 66-byte record to output 


BLBS 

RO.LOOP 

On success, continue loop 


BRB 

EXIT4 

On error, signal and exit 

f 

; Close 

the source and destination files 


f 

F_ERR: 

PUSHL 

FAB$L_STV(R6) 

Push STV and STS fields 


PUSHL 

FAB$L_STS(R6) 

on stack 


CALLS 

#2. G~LIB$SIGNAL 

Signal file error 


BRB 

EXIT 

Exit 

R.ERR: 

PUSHL 

RAB$L_STV(R6) 

Push STV and STS fields 


PUSHL 

RAB$L_STS(R6) 

on stack 


CALLS 

#2, G“LIB$SIGNAL 

Signal file error 

CLOSE: 

$CLOSE 

FAB=DST_FAB 

Close output file 


$CL0SE 

FAB=SRC_FAB 

Close input file 

EXIT: 

$EXIT_S 


Exit 


.END 

CREATEIDX 

Specify starting address 


This example program creates an indexed file with a primary key and two 
alternate keys that are defined by appropriate key definition control blocks 
(XABKEY). For efficiency, the file is divided into areas consisting of a data 
area and an index area for each key using multiple allocation control blocks 
(XABALL). 
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In each XABKEY, the DAN and IAN arguments (XAB$B_DAN and XAB$B_ 
IAN fields) indicate the area identification number (AID) of the corresponding 
XABALL. By setting the LOA bit in RAB field RAB$L_ROP, the program 
indicates that VAX RMS should use the DFL and IFL arguments (XAB$W_ 
DFL and XAB$W_IFL fields) to determine the maximum initial fill size (in 
bytes) for data and index buckets (each bucket contains the number of blocks 
specified in the XABALL BKZ argument, XAB$B_BKZ field). 

These are the the XABKEY and XABALL control blocks for the primary key 
(the NAME key) in this example: 


DST.KEYO: 

$XABKEY REF=0,- 
DAN=0,- 
DFL=1536,- 
IAN=1,- 
IFL=1536,- 
PROLOGS, - 


Primary key is Name 
Key reference number 
Define data XABALL 
Define data fill of 75% 
Define index XABALL 
Initial index fill 75% 
Request Prolog 3 


DST_ALLO: 

$XABALL AID=0.- 

ALQ=328,- 
A0P=<CBT>,- 
BKZ=4.- 
DEQ=112,- 
NXT=DST_ALL1 

DST.ALL1: 

$XABALL AID=1.- 
ALQ=8,- 
AOP=<CBT>.- 
BKZ=4,- 
DEQ=4.- 
NXT=DST_ALL2 


Data area definition 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 

Primary key index area 
Allocation quantity and 
contiguous best try 
Bucket size of 4 blocks 
Default extension quantity 
Designate next XAB 


The allocation information was obtained using the File Definition Language 
(FDL) editor which is especially useful when creating large indexed files. The 
DCL commands CREATE/FDL and CONVERT can be used to create files by 
using an FDL file produced by the FDL editor, without any programming. 
Instead of using the multiple XABs for the key definition and area allocations 
in this program, a simpler approach is to use the FDL file produced by the 
FDL editor by invoking the FDL routines FDL$PARSE and FDL$RELEASE 
(for more information on these routines, see the VAX/VMS Utility Routines 
Reference Manual). 


Fixed-length records are copied from the sequential input file on the local 
node to the indexed file on the remote node. Each variable-length output 
record will initially be 66 bytes long and may be extended to a maximum of 
128 bytes. A subsequent example in this document shows how to access this 
file using different key paths. 
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4.2 Processing File Specifications 

The file name and file specification services. Parse and Search, are used for 
relatively complex operations, such as processing wildcard characters. 

Before you can perform operations on a file, you must establish a path to 
the file. You do this by specifying the file specification string address and 
size (FAB$L_FNA and FAB$B_FNS) fields (and possibly the default file 
specification string address and size fields) of the FAB to describe an ASCII 
string within the program. In this ASCII string, you can have a concatenation 
of the network node name; a logical or device name; the directory name; and 
the file name, type, and version number. 

If a logical name is used, VAX RMS translates the logical name into 
its equivalent file specification before it applies defaults to any missing 
components of the file specification. If the logical name is a search list 
logical name, VAX RMS translates each element of the search list into an 
equivalent file specification before it applies defaults to that element. When 
using the Search service, a file specification that may contain a search list 
logical name must be handled as if wildcard characters were present in the 
file specification. 

The Parse service is required prior to the Search service in order to examine 
the file specification for wildcard characters or a search list. If the file is 
found, the Parse service sets a NAM block bit that VAX RMS uses internally 
and sets an appropriate value in the wildcard character context which is used 
as input by the Search service. The Parse service is invoked once, then the 
Search service is repetitively invoked as many times as there are files that 
match the original file specification. 

If a wildcard is present, the Search service will attempt to find all files 
that match the file specification. If an asterisk (*) is in the directory field, 
all directories on the specified device are searched for files that match the 
remaining file specification components. Like the use of wildcard characters, 
when a search list logical name is present, a single Parse service and multiple 
Search services return all files that match the file specification. With search 
lists, however, all list elements are searched for matching file specifications 
in the specified order without regard to uniqueness between the resulting file 
specifications. Search lists can be used in place of (or in addition to) wildcard 
characters to specify a more efficient search order, which can mean different 
combinations for the device, directory, file name, file type, and version 
number parts of a file specification. Search lists can also contain wildcard 
characters, if needed. 

In summary, the Parse and Search services use a search list logical name very 
much like a wildcard. Unlike the case of opening a file, in which the first 
instance where the file is found successfully ends the use of additional search 
list file specifications, the Parse and Search services use all search list file 
specifications. 

Example 4-3 shows how the SPARSE and SSEARCH macros can be used in 
wildcard processing. 
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Example 4-3 Use of Parse and Search Services 


.TITLE WILD 

Program to accept wildcard characters in input (partial) file 
specification and display full file specification. 




SNAMDEF 

i 

; NAM block definitions 

.PSECT 

DATA,NOEXE,WRT 


NAM.BLK: 

$NAM 

RSA=RES_STR,- 

Result buffer address 


RSS=NAM$C_MAXRSS,- 

Result buffer size 


ESA=EXP_STR,- 

Expanded buffer address 


ESS=NAM$C_MAXRSS 

Expanded buffer size 

FAB.BLK: 



$FAB 

F0P=NAM,- 

Use NAM block option 


NAM=NAM_BLK,- 

Pointer to NAM block 


FNA=INP_STR 

Addr of file name string 

EXP.STR: 


Expanded string buffer 

.BLKB 

NAM$C_MAXRSS 


RES.STR: 


Resultant string buffer 

.BLKB 

NAM$C_MAXRSS 


RES_STR_D: 


Resultant string descriptor 

. BLKL 

1 


.LONG 

RES_STR 


INP.STR: 


; Input string buffer 

.BLKB 

NAM$C_MAXRSS 


INP_STR_D: 


; Input string descriptor 

.LONG 

NAM$C_MAXRSS 


.LONG 

INP.STR 


INP_STR_LEN: 


; Input string length 

.BLKL 

1 


PROMPT.D: 


; User prompt string 

.ASCID 

/Please enter the file specification: / 

.PSECT 

CODE,EXE,NOWRT 


.ENTRY 

WILD,‘M<> 


PUSHAB 

INP.STR.LEN 

; Address for string length 

PUSHAB 

PROMPT.D 

; Prompt string descriptor 

PUSHAB 

INP.STR.D 

; String buffer descriptor 

CALLS 

#3,G‘LIB$GET_INPUT 

; Get input string value 

BLBC 

RO.EXIT 

; Quit on error 



Store user input string and perform initial parse to 
set up VAX RMS context for subsequent search. 


MOVB INP_STR_LEN, - 

FAB_BLK+FAB$B_FNS 
SPARSE FAB=FAB_BLK 
BLBC RO.F.ERR 


; Set string size 

; Parse the file spec 
; Quit and signal on error 


Search until all possibilities are exhausted. 


SEARCH.LOOP: 

SSEARCH FAB=FAB_BLK 
BLBC RO.SRCHERR 


; Find next file 
; Any more? 


Print out the resultant string from the search operation 



MOVZBL NAM_BLK+NAM$B_RSL, - 
RES_STR_D 
PUSHAB RES.STR.D 
CALLS #1,G~LIB$PUT_OUTPUT 
BLBC RO,EXIT 

BRB SEARCH.LOOP 


; Set string length 
; String descriptor 
; Output the result 
; Quit on error 
; Go for more 


(Continued on next page) 
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Example 4-3 (Cont.) Use of Parse and Search Services 


SRCHERR: 


If the error is "No more 
files" then this is the 
normal completion of the 
search loop. 


CMPL RO,#RMS$_NMF 

BEQL S.EXIT 


F.ERR: PUSHL FAB_BLK+FAB$L_STV 


Push STV and STS on stack 
in reverse order 
Signal error 
Suppress "No More Files" 


PUSHL FAB_BLK+FAB$L_STS 
CALLS #2. G~LIB$SIGNAL 


S.EXIT: MOVL #1,R0 
EXIT: RET 

.END WILD 


This program is designed to locate all files corresponding to a partial file 
specification input. The program prompts the user for an input string, which 
can consist of a partial file specification, using the wildcard characters and 
/or any type of logical name, including a search list logical name. In many 
respects, this program emulates the DCL command DIRECTORY, which is 
discussed in the VAX/VMS DCL Dictionary. 

The program illustrates the use of the SPARSE and $SEARCH file name 
processing macros. Here is the program statement that invokes the Parse 
service for parsing the file name string: 

SPARSE FAB=FAB_BLK 

Before invoking the Parse service (SPARSE macro), the program moves the 
input string length to the file name string (FAB$B_FNS) field. If the Parse 
service returns an error completion status, the program branches to the F_ 
ERR: error routine. 

Assuming no error, the program searches the disk directories specified by the 
expanded string area address field in the NAM block (NAM$L__ESA) until all 
possible files conforming to the partial file specification input are found. Here 
is the program line that invokes the Search service: 

ISEARCH FAB=FAB_BLK 

A status test is performed immediately after the $SEARCH macro. If an error 
is detected, the program will branch to a label called SRCHERR:. If a no- 
more-files condition is detected, VAX RMS returns the RMS$_NMF message 
to indicate that all files that match the specification have been found. (This 
error, however, is not signaled.) 

This program contains two Run-Time Library procedures: LIB$GET_INPUT 
and LIB$PUT_OUTPUT. The LIB$GET_INPUT procedure inputs a record 
from the current controlling input device, specified by SYS$INPUT, using the 
VAX RMS Get service. The LIB$PUT_OUTPUT procedure outputs a record 
(line) to the current controlling output device, specified by SYS$OUTPUT, 
using the VAX RMS Put service. Both procedures are discussed in greater 
detail in the VAX/VMS Run-Time Library Routines Reference Manual. 
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4.3 Connecting and Disconnecting Record Streams 

To associate or disassociate a file with one or more record streams, VAX RMS 
provides the Connect and Disconnect services, which are invoked using the 
$CONNECT and $DISCONNECT macros. 

Before reading and writing file records, the program must open (or create) 
the input and output files and then connect the files to the appropriate record 
streams by executing the following macros: 

1 $OPEN (or $CREATE) 

2 $CONNECT 

Closing a file disconnects the record stream implicitly. Use the Disconnect 
service to explicitly disconnect a record stream that is not immediately being 
used. This will keep the file open but will release various data structures for 
use by other processes until your program needs the record stream. 

Example 4-4 shows a program in which a user-entered reply determines 
which key path is selected to access the indexed file created by a previously- 
defined example program. Example 4-2. The user-entered value determines 
the value specified for the RAB$B_KRF field. The RAB$B__KRF value is set 
before the connect operation occurs because this field is input to the Connect 
service. 
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Example 4-4 Use of the Connect Service and Multiple Keys 


.TITLE MULTIKEY 


REC_SIZE=128 

.PSECT 


MODFAB: $FAB 


MODRAB: $RAB 


REC.START: 

REC.MODBUF: 

MPROO: .ASCID 

MPR01: .ASCID 

ENTRYERR: 


DATA NOEXE.LONG 


** RMS DATA ** 


FNM=<DATA_OUTPUT.DAT> 
FAC=<GET>,- 
SHR=<GET, UPD, PUT>,- 
MRS=REC_SIZE 
FAB=MODFAB,- 
MBF=3,- 

UBF=REC_MODBUF.- 
USZ=REC_SIZE,- 
KRF=0 

.LONG REC.SIZE 
.ADDRESS REC.MODBUF 
.BLKB REC.SIZE 


FAB file spec. 

Get access needed 
Allow Get, Update, Put 
Specify record size 
RAB; indicate FAB 
Use 3 buffers 
Specify buffer 

Primary is default key 
Record buffer 


TERMINAL I/O DATA ** 

/ / 

/Enter list order: 1-by name, 2-by city, 3-by state, 9-end 
.ASCID /* * Value entered must be 1, 2, 3, or 9. * */ 


:/ 


REGANS: .LONG 1 

.ADDRESS REGBUF 
REGBUF: .BLKB 1 

DONE: .ASCID /Press RETURN to continue/ 



.PSECT 

CODE 

START: 

.WORD 

~M<> 

INPUT: 

PUSHAL 

MPROO 


PUSHAL 

MPR01 


PUSHAL 

REGANS 


CALLS 

#3, G~LIB$GET_INPUT 


BLBC 

RO.FINI 


CMPB 

#~A/1/.REGBUF 


BEQLU 

PRIM 


CMPB 

#~A/2/.REGBUF 


BEQLU 

ALT1 


CMPB 

#~A/3/,REGBUF 


BEQLU 

ALT2 


CMPB 

#~A/9/,REGBUF 


BNEQU 

BADANS 


BRB 

FINI 

BADANS: 

PUSHAL 

ENTRYERR 


CALLS 

#1, G~LIB$PUT_OUTPUT 


BLBC 

RO.FINI 


BRW 

INPUT 

PRIM: 

MOVB 

#0,MODRAB+RAB$B_KRF 


BRW 

OPEN 

ALT1: 

MOVB 

#1.MODRAB+RAB$B_KRF 


BRW 

OPEN 

ALT2: 

MOVB 

#2,MODRAB+RAB$B_KRF 

OPEN: 

$0PEN 

FAB=MODFAB 


BLBC 

RO,ERROR.OPEN 


$C0NNECT RAB=MODRAB 


BLBC 

RO,ERROR 


; Get input 
; Display prompt 


Test value of menu answer 

1 means primary 
Continue testing 

2 means first alternate 
Continue testing 

3 means second alternate 
Continue testing 

Entry not 0, i, 2, 9 
9 means end program 
Display error message 


; Entry error; retry 
; Set key of reference in RAB 

; Set key of reference in RAB 

; Set key of reference in RAB 
; Open file 

; Connect record stream 


(Continued on next page) 
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Example 4-4 (Cont.) Use of the Connect Service and Multiple Keys 


NEXT: $GET 

RAB=MODRAB 

; Get record 

CMPL 

#RMS$_E0F,R0 

; Test if EOF 

BEQLU 

CLEAN 


BLBC 

RO.ERROR 


MOVZWL 

RAB$W_USZ+MODRAB,REC_START ; Set ASCII descriptor length 

PUSHAL 

REC.START 

; Display each record 

CALLS #1. G~LIB$PUT_OUTPUT 


BLBC 

RO.FINI 


BRW 

NEXT 

; Repeat until EOF 

CLEAN: $CL0SE 

FAB=MODFAB 

; Close file 

BLBC 

RO.ERROR.OPEN 


PUSHAL 

MPROO 


CALLS #1, G~LIB$PUT_OUTPUT 


BLBC 

RO.FINI 


PUSHAL 

DONE 


PUSHAL 

REGANS 


CALLS #2, G~LIB$GET_INPUT 


BLBC 

RO.FINI 


JMP 

INPUT 


ERROR.OPEN: 



PUSHL 

MODFAB+FAB$L_STV 

; Error opening 

PUSHL 

MODFAB+FAB$L_STS 

; file. Signal error 

CALLS 

#2. G“LIB$SIGNAL 

; using LIB$SIGNAL. 

BRW 

FINI 

; End program 

ERROR: PUSHL 

MODRAB+RAB$L_STV 

; Record-related error 

PUSHL 

MODRAB+RAB$L_STS 


CALLS 

#2, G~LIB$SIGNAL 

; Signal error, then 

$CL0SE 

FAB=MODFAB 

; close file 

FINI: RET 



.END 

START 



Here the SHR argument limits access to processes that perform the Get 


service. 

Put service, and Update service. If you anticipate no file modifications 


as your program accesses the file, you can improve performance by having the 
SHR argument limit access to processes that use the Get service (SHR=GET). 


Errors are signaled according to the recommended practice of using the 


FAB$L. 

_STS and FAB$L_STV fields for file errors and RAB$L_STS and 


RAB$L. 

_STV fields for record errors. 


4.4 Other File-Processing Operations 

Other VAX RMS file services include the Display, Erase, Extend, Remove, 
and Rename services, which can be invoked using the $DISPLAY, $ERASE, 
$EXTEND, $REMOVE, and $RENAME macros, respectively. 

Example 4-5 illustrates the use of the Rename service to rename a file from 
directory [USER] named NAMES.DAT to directory [USER.HISTORY] named 
OLD_NAMES.DAT. 
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Example 4-5 


Use of the Rename Service 


.TITLE RENAME 


Program that renames a file into a different directory said 
displays the resultsmt string. 

.PSECT DATA,NOEXE,WRT 


; Define old FAB, old NAM, new FAB, new NAM, and buffers 


OLD.FAB: 

$FAB 

OLD.NAM: 

$NAM 


NEW.FAB: 

$FAB 

NEW.NAM: 

$NAM 


FNM=<[USER]NAMES.DAT>, 
NAM=OLD_NAM 

ESA=EXP_OLD,- 
ESS=NAM$C_MAXRSS,- 
RSA=RES_OLD,- 
RSS=NAM$C_MAXRSS 

FNM=<[USER.HISTORY]OLD 
NAM=NEW_NAM 

ESA=EXP_NEW,- 
ESS=NAM$C_MAXRSS,- 
RSA=RES_NEW,- 
RSS=NAM$C_MAXRSS 


; Define old file FAB 

; Pointer to NAM block 
; Define old file NAM 
; Equivalence string 
; address said size 
; Resultsmt string 
; address and size 
; Define new file FAB 
NAMES.DAT>,- 
; Pointer to NAM block 

; Equivalence string 
; address smd size 
; Resultsmt string 
; address and size 


EXP.OLD: 

. BLKB 

EXP.NEW: 

.BLKB 

RES.OLD: 

.BLKB 

RES_OLD_D: 

. BLKL 
.LONG 

RES.NEW: 

.BLKB 

RES_NEW_D: 

.BLKL 

.LONG 


NAM$C_MAXRSS 

NAM$C_MAXRSS 

NAM$C_MAXRSS 

1 

RES.OLD 

NAM$C_MAXRSS 

1 

RES.NEW 


Old file equivalence 

string buffer 

New file equivalence 

string buffer 

Old file resultant 

string buffer 

String descriptor 


New file resultsmt 
string buffer 
String descriptor 


MESS: 


.ASCID /has been successfully relocated to / 


.PSECT CODE,EXE,NOWRT 
.ENTRY RENAME,-M<> 

; Rename file 


$RENAME OLDFAB=OLD_FAB, NEWFAB=NEW_FAB 
BLBC RO,ERROR 

; Set up descriptors 

MOVZBL OLD_NAM+NAM$B_RSL,RES.OLD.D 
MOVZBL NEW_NAM+NAM$B_RSL,RES.NEW.D 


PUSHAL 

RES.OLD.D 

CALLS 

#1,G~LIB$PUT_OUTPUT 

BLBC 

RO,TERM.ERROR 

PUSHAL 

MESS 

CALLS 

#1,G~LIB$PUT_OUTPUT 

BLBC 

RO.TERM.ERROR 

PUSHAL 

RES.NEW.D 

CALLS 

#1.G~LIB$PUT_OUTPUT 

BLBS 

RO,DONE 


Push resultsmt nsune, 
display old file spec. 
Brsmch on error 
Push message on stack, 
display message 
Brsmch on error 
Push resultsmt nsone, 
display new file spec. 
Branch on success 


(Continued on next page) 
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Example 4-5 (Cont.) Use of the Rename Service 


TERM.: 

ERROR: 




PUSHL 

RO 

; Signal output error 


CALLS 

BRB 

#1,G~LIB$SIGNAL 

DONE 

; from RO 

ERROR 

PUSHL 

OLD_FAB+FAB$L_STV 

; Push STV and STS on 


PUSHL 

OLD_FAB+FAB$L_STS 

; stack (reverse order) 

DONE: 

CALLS 

RET 

#2,G~LIB$SIGNAL 

; Signal error 


.END RENAME 



This program uses the Rename service to change both the directory and the 
name of the object file, which is being replaced by a new file (created by a 
separate program). If the Rename service executes correctly, the resultant 
file specification of the old file, the message defined by the ASCII descriptor 
following the label MESS:, and the resultant file specification of the new file 
are displayed as verification that the Rename service successfully completed. 


4.5 Retrieving and Inserting Records 

The record-processing services provided by VAX RMS insert records into a 
file and retrieve records from a file. These services are the Find, Get, and 
Put services, which can be invoked by the $FIND, $GET, and $PUT macros, 
respectively. 

Example 4-6 illustrates the use of the $GET and $PUT macros. It connects 
the input and output record streams, reads a record from an indexed file, and 
writes the record to a relative file. The program illustrates the use of the key 
string buffer, the key string descriptor and the key string length when reading 
indexed records and it includes the use of a user prompt string. 
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Example 4-6 Use of the Get and Put Services 


.TITLE LOOKUP 


This program looks up records in the input file and 
writes the records to the output file. 



.PSECT 

DATA,WRT,NOEXE 


INFAB: 

$FAB 

FNM = <INFILE:>,- 

Input file logical name 



SHR = <GET,PUT,UPD,DEL> 

Allow read/write sharing 

INRAB: 

$RAB 

FAB = INFAB,- 

Pointer to FAB 



KBF = INP.STR,- 

Key buffer 



KRF = 0.- 

Primary key 



RAC = KEY,- 

Keyed access 



ROP = WAT,- 

Wait for record 



UBF = REC.BUFF,- 

Record buffer 



USZ = REC.SIZE 

and size 

OUTFAB: 

$FAB 

FNM = <OUTFILE: >, - 

Output file logical name 



BKS = 3,- 

3 blocks per bucket 



MRS = REC.SIZE,- 

Maximum record size 



ORG = REL,- 

Relative file 



RAT = CR 

Implied carriage control 

OUTRAB: 

$RAB 

FAB = OUTFAB,- 

Pointer to FAB 



RBF = REC.BUFF 

Output uses same buffer 
as input 

REC.SIZE = 132 
REC.BUFF: 


Maximum size records 


.BLKB 

REC.SIZE 

; Record buffer 

INP.STR: 

. BLKB 

REC.SIZE 

; Key string buffer 

INP.STR. 

.D: 


; Key string descriptor 


.LONG 

REC.SIZE 



.LONG 

INP.STR 


INP.STR. 

.LEN: 

i 

; Key string length 


. BLKL 

1 


PROMPT.! 

): 

.ASCID 

/Please input key value: 

; User prompt string 
/ 


.PSECT 

CODE.NOWRT.EXE 



; Initialization - Open input and output 

files and connect str< 


.ENTRY 

LOOKUP,~M<> 

No registers to save 


$0PEN 

FAB=INFAB 

Open input file 


BLBC 

R0.EXIT1 

Quit on error 


$C0NNECT RAB=INRAB 

Connect to input 


BLBC 

R0.EXIT2 

Quit on error 


$CREATE FAB=OUTFAB 

Create output file 


BLBC 

R0.EXIT3 

Quit on error 


ICONNECT RAB=OUTRAB 

Connect to output 


BLBC 

R0.EXIT4 

Quit on error 


BRB 

READ 

Skip error branching 

EXIT1: 

MOVAL 

INFAB, R6 

Keep INFAB address 


BRW 

F.ERR 

Signal FAB error 

EXIT2: 

MOVAL 

INRAB, R6 

Keep INRAB address 


BRW 

R.ERR 

Signal RAB error 

EXIT3: 

MOVAL 

OUTFAB, R6 

Keep OUTFAB address 


BRB 

F.ERR 

Signal FAB error 

EXIT4: 

MOVAL 

OUTRAB. R6 

Keep OUTRAB address 


BRB 

R.ERR 

Signal RAB error 

; Loop 

to copy 

records 



(Continued on next page) 
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Example 4-6 (Cont.) Use of the Get and Put Services 


READ: 

PUSHAB 

INP_STR_LEN 


PUSHAB 

PROMPTED 


PUSHAB 

INP.STR.D 


CALLS 

#3,G“LIB$GET_INPUT 


BLBS 

RO,GET 


CMPL 

RO,#RMS$_EOF 


BEQL 

DONE 


BRB 

EXIT 

GET: 

MOVB 

INP.STR.LEN, - 
INRAB+RAB$B_KSZ 


$GET 

RAB=INRAB 


BLBS 

RO.PUT 


CMPL 

RO,#RMS$_RNF 


BEQL 

READ 


BRB 

EXIT2 

PUT: 

MOVW 

INRAB+RAB$W_RSZ, - 
OUTRAB+RAB$W_RSZ 


$PUT 

RAB=OUTRAB 


BLBC 

R0.EXIT4 


BRB 

READ 

; Close 

files and exit 

F_ERR: 

PUSHL 

FAB$L_STV(R6) 


PUSHL 

FAB$L_STS(R6) 


CALLS 

#2, G~LIB$SIGNAL 


BRB 

EXIT 

R_ERR: 

PUSHL 

RAB$L_STV(R6) 


PUSHL 

RAB$L_STS(R6) 


CALLS 

#2, G~LIB$SIGNAL 

DONE: 

$CL0SE 

FAB=INFAB 


$CLOSE 

FAB=OUTFAB 

EXIT: 

RET 



.END 

LOOKUP 


Address for string length 
Prompt string descriptor 
String buffer descriptor 
Get input string value 
Quit on error or end-of-file 
Was error end-of-file? 
Successful completion 
Error otherwise 
Set key size 

Get a record 
Put if successful 
No such record? 

Try again 
Error otherwise 
Set the record size 
for output 
Write the record 
Quit on error 
Go back for more 


; Push STV and STS on 
; stack in reverse order 
; Signal message 

; Push STV and STS on 
; stack in reverse order 
; Signal message 
; Close input 
; and output 

; Return with status in RO 


This program writes records from an existing indexed input file into a newly- 
created relative output file. 

The program configures the file-sharing field (FAB$B_SHR) in the input FAB 
to permit sharing of the file by processes that use the Get, Put, Update and 
Delete services. 

The output FAB sets the bucket size field (FAB$B_BKS) at 3 blocks per 
bucket, limits the record size in the output file to 132 bytes, specifies the 
relative file organization and specifies an implicit carriage control when the 
file output is directed to a terminal. 

The RAB for the input file establishes the key data, sets the WAIT record 
option and defines the record buffer. The output RAB locates the record 
buffer. The rest of the first program section assigns values and allocates 
space to various program variables. After the program opens and creates the 
two files and connects the record streams, it executes a series of instructions 
at label READ: that input the required key values and the user prompt. 

Then the program uses the $GET and $PUT macros to invoke the respective 
services for retrieving and inserting the records. The $GET macro uses the 
INRAB, and the $PUT macro uses the OUTRAB as shown in the following 
program statements: 

$GET RAB=INRAB 
$PUT RAB=OUTRAB 
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Each time the program reads or writes a record, it performs a status check. 
If the status check is successful, the program branches back to READ: for 
the next record. If any of the status checks indicate an error, the program 
branches to the appropriate error handler before exiting. 

When the program completes the records transfers, it branches to label 
DONE: to close the record and exit. 


4.6 Deleting Records 

This service can only be used with relative and indexed files. Example 4-7 
illustrates use of the Delete service. 
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Example 4-7 Use of the Delete Service 


.TITLE 

DELETE 


f 

; This program 

looks up records in the input file and 

; deletes those 

• 

records. 


• 

.PSECT 

DATA,WRT,NOEXE 


INFAB: $FAB 

FNM = <INFILE:>,- 

Input file logical name 


FAC = <DEL,GET> 

DEL access 

INRAB: $RAB 

FAB = INFAB,- 

Pointer to FAB 


KBF = INP.STR,- 

Key buffer 


KRF = 0,- 

Primary key 


RAC = KEY 

Keyed access 

REC.SIZE = 132 


Maximum size records 

INP.STR: 


Key string/record buffer 

. BLKB 

REC.SIZE 


INP.STR.D: 


; Key string descriptor 

.LONG 

REC.SIZE 


.LONG 

INP.STR 


INP.STR.LEN: 


; Key string length 

.BLKL 

1 


KEY.PMT.D: 


; Key value prompt string 

.ASCID 

/Please enter key value: 

/ 

.PSECT 

C0DE.N0WRT.EXE 


; Initialization - Open file and connect 

stream 

.ENTRY 

DELETE,~M<> 

; No registers to save 

$OPEN 

FAB=INFAB 

; Open input file 

BLBC 

RO,F_ERR 

; Quit on error 

$CONNECT RAB=INRAB 

; Connect to input 

BLBC 

RO,R_ERR 

; Quit on error 

I 

; Delete record 

loop 


» 

READ: 



PUSHAB 

INP.STR.LEN 

Address for string length 

PUSHAB 

KEY.PMT.D 

Prompt string descriptor 

PUSHAB 

INP.STR.D 

String buffer descriptor 

CALLS 

#3,G~LIB$GET_INPUT 

Get input string value 

BLBS 

RO.FIND 

Quit on error or end-of-file 

CMPL 

RO,#RMS$_E0F 

Was error end-of-file? 

BEQL 

DONE 

Successful completion 

BRB 

EXIT 

Error otherwise 

FIND: MOVB 

INP.STR.LEN, - 

Set key size 


INRAB+RAB$B_KSZ 


$FIND 

RAB=INRAB 

Locate the record 

BLBS 

RO,DEL 

Continue if found 

CMPL 

RO,#RMS$_RNF 

No such record? 

BEQL 

READ 

Try again 

BRB 

R.ERR 

Error otherwise 

DEL: $DELETE RAB=INRAB 

Delete the record 

BLBC 

RO,R.ERR 

Quit on error 

BRB 

READ 

Go back for more 


Close files and exit 


(Continued on next page) 
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Example 4-7 (Cont.) Use of the Delete Service 


F_ERR: 

PUSHL 

FAB$L_STV+INFAB 

; Push STV and STS 

on 


PUSHL 

FAB$L_STS+INFAB 

; stack in reverse 

order 


CALLS 

*2. G~LIB$SIGNAL 

; Signal message 



BRB 

EXIT 



R_ERR: 

PUSHL 

RAB$L_STV+INRAB 

; Push STV and STS 

on 


PUSHL 

RAB$L_STS+INRAB 

; stack in reverse 

order 


CALLS 

#2, G~LIB$SIGNAL 

; Signal message 


DONE: 

$CLOSE 

FAB=INFAB 

; Close files 


EXIT: 

RET 


; Return with status in RO 


.END 

DELETE 




This program uses a key to find and delete a record. To use the $DELETE 
macro, the $FAB macro for the file must specify that the FAB$V_DEL bit is 
marked in the file access (FAB$B_FAC) field as shown here: 

INFAB: $FAB FNM=<INFILE: >, - 

FAC=<DEL> 

Flere is the program statement that invokes the Delete Service and points to 
the input RAB: 

SDELETE RAB=INRAB 


Updating Records 

Example 4-8 illustrates the use of the Update service. 
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Example 4-8 Use of the Update Service 


.TITLE UPDATE 

This program looks up records in the input file and 
updates those records. 


.PSECT 

DATA,WRT,NOEXE 

INFAB: $FAB 

FNM * <INFILE:>,- 
FAC = <GET,UPD> 

INRAB: $RAB 

FAB = INFAB,- 
KBF ■ INP.STR,- 
KRF = 0.- 
RAC = KEY,- 
RBF = INP.STR 

REC.SIZE = 132 

INP.STR: 

. BLKB 

REC.SIZE 

INP_STR_D: 

.LONG 

REC.SIZE 

.LONG 

INP.STR 

INP_STR_LEN: 

. BLKL 

1 

KEY_PMT_D: 

.ASCID 

/Please input key 

DATA_PMT_D: 

.ASCID 

/Please input new 

.PSECT 

C0DE.N0WRT.EXE 


Input file logical name 

Read and Write access 

Pointer to FAB 

Key buffer 

Primary key 

Keyed access 

Record buffer 

Maximum size records 
Key string/record buffer 

Key string descriptor 


; Key string length 

; Key value prompt string 
value: / 

; Data value prompt string 
record value: / 


Initialization - Open file and connect stream 


.ENTRY UPDATE.“M<> 

$0PEN FAB=INFAB 
BLBC RO.FAB.E 

$CONNECT RAB=INRAB 

BLBC RO.RAB_E 

BRB READ 

FAB.E: BRW F.ERR 

RAB.E: BRW R_ERR 


No registers to save 
Open input file 
Quit on error 
Connect to input 
Quit on error 
Begin update loop 
File (FAB) error 
Record (RAB) error 


Update record loop 


READ: 


Prompt for key value to look up. 


ALL.D: 
FIND: 


PUSHAB 

INP.STR.LEN 

PUSHAB 

KEY.PMT.D 

PUSHAB 

INP.STR.D 

CALLS 

#3,G“LIB$GET_INPUT 

BLBS 

RO.FIND 

CMPL 

RO.#RMS$_E0F 

BEQL 

ALL.D 

BRW 

EXIT 

BRW 

DONE 

MOVB 

INP.STR.LEN, - 
INRAB+RAB$B_KSZ 

$FIND 

RAB=INRAB 

BLBS 

RO.UPD 

CMPL 

RO,#RMS$_RNF 

BEQL 

READ 

BRB 

R.ERR 


Address for string length 
Prompt string descriptor 
String buffer descriptor 
Get input string value 
Quit on error or end-of-file 
Was error end-of-file? 
Successful completion 
Error otherwise 

Set key size 

Locate the record 
Continue if found 
No such record? 

Try again 
Error otherwise 


Prompt for new data record. 


(Continued on next page) 
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Example 4-8 (Cont.) Use of the Update Service 


UPD: 



PUSHAB 

INP.STR.LEN 

Address for string length 


PUSHAB 

DATA.PMT.D 

Prompt string descriptor 


PUSHAB 

INP_STR_D 

String buffer descriptor 


CALLS 

#3,G~LIB$GET_INPUT 

Get input string 

value 


BLBC 

RO.EXIT 

Quit on error 



MOVW 

INP.STR.LEN, - 
INRAB+RAB$W_RSZ 

Set record size 



IUPDATE RAB=INRAB 

; Write the record 



BLBC 

RO,R.ERR 

; Quit on error 



BRW 

READ 

; Go back for more 


; Close 

files and exit 



F_ERR: 

PUSHL 

FAB$L_STV+INFAB 

Push STV and STS 

on 


PUSHL 

FAB$L_STS+INFAB 

stack in reverse 

order 


CALLS 

#2, G~LIB$SIGNAL 

Signal message 



BRB 

EXIT 



R.ERR: 

PUSHL 

RABIL.STV+INRAB 

Push STV and STS 

on 


PUSHL 

RABIL.STS+INRAB 

stack in reverse 

order 


CALLS 

#2, G~LIB$SIGNAL 

Signal message 


DONE: 

ICLOSE 

FAB=INFAB 

Close files 


EXIT: 

RET 


Return with status in RO 


.END 

UPDATE 




This program uses a key and a new record entered from the terminal to 
update a record in the input file. 

To use the $UPDATE macro, the $FAB macro for the file must specify that 
the FAB$V_UPD bit is marked in the file access (FAB$B_FAC) field as shown 
here: 

INFAB: $FAB FNM=<INFILE:>,- 

FAC=<GET,UPD> 

Before updating a record, the program uses the Find service to locate the 
record by executing the $FIND macro located under the FIND: label. 

IUPDATE RAB=INRAB 


Using Block I/O 

In addition to the major types of record access provided by the sequential, 
random by key value or relative record number, and random by RFA access 
modes, VAX RMS provides another means to access data in a file: block I/O. 

Block I/O operations let you directly read or write the blocks of a file. These 
operations are provided for users who must keep system overhead to a 
minimum and need no interpretation of file data as logical records, yet still 
want to take advantage of the easy file access of VAX RMS. Block I/O is an 
intermediate step between the VAX RMS record operations and direct use of 
VAX/VMS $QIO system services. 

The three block I/O services are the Read, Space, and Write services, which 
can be invoked using the $READ, $SPACE, and $WRITE macros, respectively. 

You cannot perform block I/O operations on shared files. That is, file access 
for block I/O operations is denied unless the FAB$V_UPI or the FAB$V_NIL 
bit is set in the FAB$B_SHR field. 
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You specify block I/O for a record stream by setting the FAB$V_BIO bit in 
the file access (FAB$B_FAC) field as input to the Open or Create services. 

If you intend to write to the file, you must also set the PUT option in the 
FAB$B__FAC field; if you intend to read from the file, you must set the GET 
option in the FAB$B_FAC field. Setting the FAB$V_BIO bit when creating a 
relative or indexed file will cause VAX RMS to omit prologue processing for 
indexed files and initial space prezeroing in relative files. 

For files of unknown organization, block I/O is the only form of processing 
allowed. Processing proceeds identically to that for block I/O to the relative 
file organization described above. 

VAX RMS provides three services for performing block I/O: 

• The Read service transfers a specified number of bytes to memory. 

• The Space service positions a file forward or backward a specified number 
of blocks. 

• The Write service writes a specified number of bytes to a file. 

The Read and Write services always begin on a block boundary. In addition 
to the Read, Space, and Write services, you can use the following services on 
a record stream connected for block I/O operations: 

• The Disconnect service ($DISCONNECT macro) 

• The Flush service ($FLUSH macro) 

• The Next Volume service ($NXTVOL macro) 

• The Rewind service ($REWIND macro) 

These services perform miscellaneous operations or disconnect the record 
stream. They do not work on the contents of the records themselves. 


4.8.1 Mixed Block and Record I/O 

How and when VAX RMS allows you to switch between record and block 
I/O depends on the organization of the file being accessed. When accessing 
sequential files, VAX RMS allows you to switch between block I/O and 
record I/O processing with any record operations, if desired. When accessing 
relative or indexed files, switching is available only if you close and reopen 
the file. Regardless of the file being accessed, VAX RMS does not permit both 
types of processing to occur simultaneously. Furthermore, when multiple 
record streams are used for a file, all record streams must be connected in the 
same manner; there can be no mixing of block and record I/O. 

For relative and indexed files, the file must be closed and reopened to change 
whether block or record I/O will be used. The selection of record or block 
I/O is specified by the FAB$B_FAC field FAB$V_BIO option being set (block 
I/O) or clear (record I/O) as input to the Create or Open service. 

For relative and indexed files, the decision to use block I/O or record I/O for 
a file can be postponed until the record stream is connected, if desired, by the 
following procedure: 

1 Set the FAB$B_FAC field FAB$V_BRO option when opening (or creating) 
the file. 
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2 Indicate the appropriate operation to the Connect service by either setting 
the RAB$V_BIO bit in the RAB$L_ROP for block I/O or by clearing it for 
record I/O. 

If multiple record streams will be used, all record streams must be connected 
for block I/O or all record streams must be connected for record I/O. 

With sequential files, if you do not need to switch between record and block 
I/O, use the FAB$B_FAC field FAB$V_BIO option to specify whether block 
or record I/O will occur as input to the Open or Create service. 

Unlike relative and indexed files, you can switch between block and record 
I/O for a sequential file when an operation has completed. To allow a 
sequential file's record stream to switch modes: 

1 Set the FAB$V_BRO option in the FAB$B_FAC field as input to the Create 
or Open service. 

2 Clear the RAB$L_ROP field RAB$V_BIO option as input to the Connect 
service. 

This procedure informs VAX RMS that it should check, after each operation, 
the RAB$V_BIO option in the RAB$L_ROP field to determine whether block 
I/O or record I/O should occur. To execute a block I/O operation: 

1 Set the RAB$L_ROP field RAB$V_BIO option. 

2 Invoke a VAX RMS block I/O service (Read, Space, or Write). 

To execute a record I/O operation: 

1 Clear the RAB$L_ROP field RAB$V_BIO option. 

2 Invoke a VAX RMS record I/O service. 

As shown, the setting of the RAB$L_ROP field RAB$V_BIO option can be 
changed to switch between block and record I/O for subsequent operations 
on the same record stream on a per operation basis. 

If you do choose to mix record and block I/O operations for sequential files, 
you must exercise caution. When you switch operations on disk devices, 
the context of the current record, next record, and the next block pointer is 
undefined. Thus, the first operation after the switch must not use sequential 
record access mode. For magnetic tape devices, the context of the next record 
or next block indicates the start of the following block on the tape for the first 
operation after the switch. 

As previously noted, you usually set the FAB$B_FAC field FAB$V_BRO 
option only for a sequential file to indicate to VAX RMS that you want to 
mix block I/O and record operations. After opening a sequential file before 
invoking the Connect service, if you decide that you want to perform block 
I/O processing only, you can set the RAB$L_ROP field RAB$V_BIO option. 
This connect-time operation overrides the setting of the FAB$V_BRO option 
for the record stream in question, and acts as a signal to the Connect service 
indicating that only block I/O will occur for this file and thus VAX RMS 
does not need to allocate internal I/O buffers. (However, you must still 
allocate buffers for block I/O operations in your user program.) When using 
multiple record streams, all other record streams must be connected in the 
same manner. If you set the FAB$V_BRO option when creating an indexed 
file, the key definition XABs for that file must be present. 
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4.8.2 The Next Block Pointer (NBP) 

For block I/O operations to sequential files on disk devices, VAX RMS 
maintains an internal next block pointer (NBP) that: 

• Points to the beginning of the file after execution of a Connect service, if 
the RAB$V_EOF option in the RAB$L_ROP field of the RAB is cleared. If 
the RAB$L_ROP field RAB$V_EOF option is set, the NPB points to the 
block following the end of file. The RAB$V_EOF option is relevant only 
for sequential files (for block I/O processing). 

• Points to the block following the highest numbered block transferred by 
an operation invoked by a Read or Write service. 

• Points to the next block following an operation invoked by the Space 
service. 

With relative and indexed files, VAX RMS does not automatically extend a 
file's allocation when using block I/O processing; an explicit Extend service is 
required. 

Example 4-9 illustrates how to copy a file using block I/O. 
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Example 4-9 Use of Block I/O 


.TITLE BLOCKIO 


This program copies the input file to the output file. 

It illustrates block I/O using the VAX RMS $READ and $WRITE 
macros. 



.PSECT 

DATA,WRT,NOEXE 

INFAB: 

$FAB 

FNM 

= 

<INFILE:>, 



FAC 

= 

<BI0,GET> 

INRAB: 

$RAB 

FAB 

= 

INFAB,- 



BKT 

= 

0,- 



UBF 

= 

REC.BUFF,- 



USZ 

= 

REC.SIZE 

OUTFAB: 

$FAB 

FNM 

= 

<0UTFILE:> 



FOP 

= 

CBT, - 



MRS 

= 

REC.SIZE,- 



FAC 

= 

<BI0,PUT>, 



RAT 

s 

CR 

OUTRAB: 

$RAB 

FAB 

= 

OUTFAB,- 



BKT 

= 

o,- 



RBF 

= 

REC.BUFF 


REC.SIZE = 1024 
REC.BUFF: 

.BLKB REC.SIZE 

.PSECT C0DE.N0WRT.EXE 


; Input file name 
; Block I/O read operations 
; Pointer to FAB 
; Start with current block 
; Record buffer 
; and size 

; Output file name 
; Try for contiguous file 
; Maximum record size 
; Block I/O write operations 
; Implied carriage control 
; Pointer to FAB 
; Start with current block 
; Output uses same buffer 
; as input 

; Maximum record size 
; Record buffer 


Initialization - Open input and output files and connect streams 



.ENTRY 

BLOCKIO, “MO 

No registers to save 


$0PEN 

FAB=INFAB 

Open input file 


BLBC 

R0.EXIT1 

Quit on error 


$C0NNECT RAB=INRAB 

Connect to input 


BLBC 

R0.EXIT2 

Quit on error 


MOVL 

INFAB+FAB$L_ALQ,- 

Set proper size 



OUTFAB+FAB$L_ALQ 

for output 


$CREATE FAB=OUTFAB 

Create output file 


BLBC 

R0.EXIT3 

Quit on error 


$C0NNECT RAB=OUTRAB 

Connect to output 


BLBC 

R0.EXIT4 

Quit on error 

; Copy 

loop 



READ: 

$READ 

RAB=INRAB 

Get a block 


BLBS 

RO,WRITE 

Write the block 


CMPL 

RO,#RMS$_E0F 

Was error end-of-file? 


BEQL 

DONE 

Successful completion 


BRB 

EXIT2 

If not, signal error 

WRITE: 

MOVW 

INRAB+RAB$W_RSZ, - 

Set the record size 



OUTRAB+RAB$W_RSZ 

for output 


$WRITE 

RAB=OUTRAB 

Write the block 


BLBC 

R0.EXIT4 

Quit on error 


BRB 

READ 

Go back for more 

; Error 

Signaling 


EXIT1: 

MOVL 

INFAB+FAB$L_STS,R2 ; 

; Move STS into R2 


MOVL 

INFAB+FAB$L_STV,R3 ; 

Move STV into R3 


BRB 

EXIT ; 

Signal error 


(Continued on next page) 
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Example 4-9 (Cont.) Use of Block I/O 


EXIT2: 

MOVL 

INRAB+RAB$L_STS,R2 

Move STS into 

R2 


MOVL 

INRAB+RAB$L_STV,R3 

Move STV into 

R3 


BRB 

EXIT 

Signal error 


EXIT3: 

MOVL 

OUTFAB+FAB$L_STS,R2 

Move STS into 

R2 


MOVL 

OUTFAB+FAB$L_STV,R3 

Move STV into 

R3 


BRB 

EXIT 

Signal error 


EXIT4: 

MOVL 

OUTRAB+RAB$L_STS,R2 

Move STS into 

R2 


MOVL 

OUTRAB+RAB$L_STV,R3 

Move STV into 

R3 


BRB 

EXIT 

Signal error 


; Close 

files and exit 



DONE: 

$CL0SE 

FAB=INFAB 

Close input and 


$CL0SE 

FAB=OUTFAB 

output files 


RET 


Return w/ success in R( 

EXIT: 

PUSHL 

R3 

Push STV and STS 


PUSHL 

R2 

on stack 



CALLS 

#2, G~LIB$SIGNAL 

Signal error 



RET 


Return w/ status in RO 


.END 

BLOCKIO 




This example program uses block I/O to transfer the contents of the input file 
to the output file. The following program data statements specify block I/O 
read operations from the input file by setting the FAB$V_BIO bit (block I/O) 
and the FAB$V_GET bit (read) in the FAB$B_FAC field of the input file's 
FAB: <FFAC): 

INFAB: $FAB FNM = <INFILE>, - ;Input file name 

FAC = <BIO,GET>,- 

The following data statements specify block I/O write read operations to the 
output file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_PUT bit 
(write) in the FAB$B_FAC field of the output file's FAB: 

OUTFAB: $FAB FNM = <INFILE>, - ;Output file name 

FAC = <BI0,PUT>,- 

The input file's contents are copied until the end of file is encountered. Any 
errors are signaled with the convention of using both the STS and STV fields 
of the appropriate control block. 


Other Record-Processing Operations 

See Part III for details of VAX RMS record services not discussed in this 
section including the Flush, Free, Next Volume, Release, Rewind, and 
Wait services. A process invokes these services using the $FLUSH, $FREE, 
$NXTVOL, $RELEASE, $REWIND, and $WAIT macros, respectively. 
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4.10 Control Routines 

In addition to the general- and special-purpose file-processing macros, VAX 
RMS provides three control routines for processing files. These routines are 
identified by the following entry point names: 

• SYS$RMSRUNDWN 

• SYSSSETDDIR 

• SYS$SETDFPROT 

These routines do not reference fields in user control blocks and are not called 
with a macro. Instead, you provide an argument list and call VAX RMS at the 
entry point for the routine. None of these routines are widely used, and none 
of them are essential to normal VAX RMS file and record processing. 

For information on these routines, see the VAX/VMS System Services Reference 
Manual . 
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Part II describes each VAX RMS control block, including a complete 
listing and description of each field. 















5 File Access Block (FAB) 


The file access block (FAB) defines file characteristics, file access, and certain 
run-time options. It also indicates whether other control blocks are associated 
with the file. 



5.1 





Summary of Fields 

Certain FAB fields are directly equivalent to certain File Definition Language 
(FDL) attributes. For information about FDL, refer to the VAX/VMS File 
Definition Language Facility Reference Manual. 

The symbolic offset, size, FDL equivalent, and a brief description of each FAB 
field are presented in Table 5-1. 

Table 5-1 FAB Fields 

Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

FAB$L_ALQ 

4 

FILE ALLOCATION 

Allocation quantity (blocks) 

FABSB—BID 1 

1 

None 

Block identifier 

FAB$B_BKS 

1 

FILE BUCKET_SIZE 

Bucket size 

FABSB—BLN 1 

1 

None 

Block length 

FAB$W_BLS 

2 

FILE MT_BLOCK_SIZE 

Magnetic tape block size 

FAB$V_CHAN 

_MODE - 2 

None 

Channel access mode 

FAB$L_CTX 

4 

FILE CONTEXT 

protection 

Context 

FAB$W_DEQ 

2 

FILE EXTENSION 

Default file extension quantity 

FAB$L_DEV 3 

4 

None 

Device characteristics 

FAB$L_DNA 

4 

FILE DEFAULT_NAME 

Default file specification string 

FAB$B_DNS 

1 

FILE DEFAULT_NAME 

address 

Default file specification string 

FAB$B_FAC 

1 

ACCESS 4 

size 

File access 

FAB$L_FNA 

4 

FILE NAME 

File specification string address 

FAB$B_FNS 

1 

FILE NAME 

File specification string size 

FAB$L_FOP 

4 

FILE 4 

File-processing options 

FAB$B_FSZ 

1 

RECORD CONTROL_FIELD_SIZE 

Fixed length control area size 

FAB$W_GBC 

2 

FILE GLOBAL_BUFFER_COUNT 

Global buffer count 


Statically initialized field (by the VAX MACRO $FAB macro) to identify this control block as a FAB. 
2 Two-bit field. 

3 Field cannot be initialized by the VAX MACRO $FAB macro. 

4 Field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 5-1 (Cont.) FAB Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

FAB$W_IFI 3 

2 

None 

Internal file identifier 

FAB$V_LNM_MODE 

_2 

None 

Logical name translation access 
mode 

FAB$L_MRN 

4 

FILE MAX_RECORD_NUMBER Maximum record number 

FAB$W_MRS 

2 

RECORD SIZE 

Maximum record size 

FAB$L_NAM 

4 

None 

Name block address 

FAB$B_ORG 

1 

FILE ORGANIZATION 

File organization 

FAB$B_RAT 

1 

RECORD 4 

Record attributes 

FAB$B_RFM 

1 

RECORD FORMAT 

Record format 

FAB$B_RTV 

1 

FILE WINDOW_SIZE 

Retrieval window size 

FAB$L_SDC 3 

4 

None 

Secondary device 
characteristics 

FAB$B_SHR 

1 

SHARING 4 

File sharing 

FAB$L_STS 3 

4 

None 

Completion status code 

FAB$L_STV 3 

4 

None 

Status values 

FAB$L_XAB 

4 

None 

Extended attribute block 
address 

2 Two-bit field. 




3 Field cannot be initialized by the VAX MACRO $FAB macro. 
4 Field contains options; corresponding FDL equivalents are listed 

in the description of the field. 


Each FAB field is described below. Unless indicated otherwise, each field is 
supported for DECnet operations on remote files with a VAX/VMS system as 
the remote node. Note that the words "DECnet operations" in the following 
descriptions refer to remote file operations between two VAX/VMS systems. 
See the VAX/VMS Networking Manual for information about the support of 
VAX RMS options for remote file access to non-VAX/VMS systems. 

To use a FAB, you must allocate program storage and specify the character 
string for the primary file specification and, optionally, the default file 
specification. The FAB$L__FNA and FAB$B_FNS fields define the primary 
file specification to VAX RMS; the FAB$L_DNA and FAB$B_DNS fields 
define the default file specification to VAX RMS. 

The format and arguments of the VAX MACRO $FAB and $FAB_STORE 
macros are defined in Appendix B. 


5-2 












File Access Block (FAB) 

FAB$I_ALQ 


5.2 FAB$L_ALQ 


The allocation quantity (ALQ) field defines the number of blocks to be 
initially allocated to a disk file when it is created (using a Create service) or to 
be added to the file when it is explicitly extended (using an Extend service). 
This field corresponds to the FDL attribute FILE ALLOCATION. 

This field contains a numeric value in the range of 0 through 4,294,967,295, 
although the maximum value depends on the number of blocks available on 
the device to be used. A value of 0 indicates no allocation. 

When you create a new file with a Create service, VAX RMS interprets the 
value in the FAB$L_ALQ field as the number of blocks for the initial extent 
of the file. If the value is 0, the minimum number of blocks for the specific 
file organization is the allocation quantity used for the initial extent. For 
example, in indexed files, only the number of blocks necessary to contain key 
and area definitions is used as the initial extent quantity when FAB$L_ALQ 
is 0. 

When an existing file is opened, VAX RMS sets the FAB$L_ALQ field to 
indicate the highest virtual block number currently allocated to the file. 

When using the Extend service, this field specifies the number of blocks to be 
added to the file. Note that VAX RMS uses this value as the extension value 
when you extend a file using the Extend service unless your program changes 
the value before it invokes the Extend service. 

Note that the value 0 is not acceptable for extending a file. 

When you use the Create and Extend services, the allocation quantity value is 
rounded up to the next disk cluster boundary; the number of blocks actually 
allocated is returned in the FAB$L_AJLQ field. 

Note that the function of the FAB$L_ALQ field with the Create and Extend 

services changes if allocation control XABs are present during the operation. 
The description of the XABALL control block (see Section 8) discusses 
allocation control XABs and their effect on the FAB$L_ALQ field during 
file creation or extension. 


5.3 FAB$B_BID 


The block identifier (BID) field is a static field that identifies a control block 
as a FAB. Once set, this field should not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
FAB$C_BID (this is done by the VAX MACRO $FAB macro). 


5.4 FAB$B_BKS 


The bucket size (BKS) field is used only for relative or indexed files to specify 
the number of blocks in each bucket of the file. This field corresponds to the 
FDL attribute FILE BUCKET_SIZE. 

This field contains a numeric value in the range of 0 to 63. If you do not 
specify a value or specify a value of 0, VAX RMS uses a default of the 
minimum number of blocks needed to contain a single record, or a minimum 
of 2 records for indexed files. If the file will be processed by RMS-11, the 
bucket size must be less than or equal to 32 blocks. 
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When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Also, certain record types contain 
control bytes; thus, the number of records per bucket multiplied by the 
number of control bytes per record equals the number of record overhead 
bytes per bucket. See the Guide to VAX/VMS File Applications for more 
information. 

Before specifying a bucket size, you must be aware of the relationship 
between bucket size and record size. You must also consider any record 
control bytes (overhead) required by VAX RMS for the type of record chosen. 
Because VAX RMS does not allow records to cross bucket boundaries, you 
must ensure that the number of blocks per bucket conforms to one of the 
formulas designed to handle one of the following: 

• Relative files with fixed-length records 

• Relative files with variable-length records 

• Relative files with VFC (variable with fixed-control) records 

• Indexed files with fixed-length records 

• Indexed files with variable-length records 

You can use the VAX EDIT/FDL Utility to determine the optimum bucket 
size. Note that if an allocation control XAB is specified, the value specified in 
the XAB$B_BKZ field will supersede the value specified in the FAB$B_BKS 
field. When multiple allocation control XABs are specified, the largest value 
in any XAB$B_BKZ field supersedes the value in the FAB$B_BKS field. Refer 
to Section 8 for information about the XAB$B_BKZ field. 

When you open an existing relative or indexed file, VAX RMS sets the 
FAB$B_BKS field to the defined size of the largest bucket size in the file. 
However, when you create a new relative or indexed file, it is strongly 
recommended that you set the FAB$B_BKS field before you invoke the 
Create service rather than use the default. 

With indexed files, note that if the FAB$B_BKS field is not specified and 
a maximum record size (FAB$W_MRS field) is specified, then VAX RMS 
will select a bucket size that allows at least one maximum-size record to 
fit. Generally, performance on record insertion and sequential retrieval on 
the primary key is improved if at least six or seven data records will fit into 
a primary data bucket. If either the bucket size or the disk cluster size is 
other than one block, then it is advisable to use a default extension quantity 
(FAB$W_DEQ) that is the least common multiple of the bucket size and 
cluster size, to avoid allocated but unused blocks within the file. 


5.5 FAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
FAB. Once set, this field should not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic value FAB$C_ 
BLN (this is done by the VAX MACRO $FAB macro). 
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5.6 FAB$W_BLS 

The block size (BLS) field is used as input only for non-disk files. This field 
usually defines the size, in bytes, of the blocks on a magnetic tape. Note that 
for some devices, this value must be an even number. This field corresponds 
to the FDL attribute FILE MT_BLOCK_SIZE. 

The FAB$W_BLS field contains a numeric value in the range of 20 through 
65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes. 
(Foreign tapes are those that are not in the standard ANSI format used by the 
VAX/VMS operating system and must be mounted using the DCL command 
MOUNT/FOREIGN.) If no value or a value of 0 is specified, the default 
selected when the volume was mounted is used. 

When you create a magnetic tape file, you can set the FAB$W_BLS field 
before you issue the Create service. In all other cases, VAX RMS ignores 
this field. When you open an existing sequential file with an Open service, 
VAX RMS returns the device buffer size. For terminals, this field defines the 
WIDTH setting; for mailboxes, this field defines the maximum message size. 

For compatibility with RMS-11, VAX RMS always rounds off the block size 
for an ANSI-formatted tape to the next highest multiple of 4. For example, if 
you set the block length to 38, VAX RMS will set it to 40. The block size of a 
foreign tape is not rounded off by VAX RMS. 

To create a magnetic tape for interchange with DIGITAL operating systems 
other than VAX/VMS, you should consult the documentation for the recipient 
system to identify possible limitations on block size. ANSI standards require 
that the block size be less than or equal to 2048 bytes. 


5.7 FAB$V_CH AIM—MODE 

The channel access mode protection (CHAN—MODE) field lets you specify 
the access mode in which the requested channel will be assigned. VAX RMS 
ignores this 2-bit field unless the program first sets either the FAB$V_UFO bit 
or the FAB$V_NFS bit in the FAB$L_FOP field. 

The FAB$V_CHAN_MODE field may contain one of the four values listed 
below with the related constant value for each shown in parenthesis. 

0 none 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 

3 User mode (PSL$C_USER) 

The default value is 0 (none), which is interpreted by VAX RMS as Executive 
mode. 

If the access mode requested is more privileged than the access mode of the 
calling process, VAX RMS uses the access mode of the caller and does not 
return an error. 

There is no corresponding FDL equivalent for this field. The FAB$V_CHAN_ 
MODE field is not supported for DECnet operations, and it is ignored during 
any DECnet remote file access. 
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To set this field from MACRO level, you include the appropriate expression as 
an argument to the $FAB macro. For example, to specify supervisor channel 
access mode, you might include a statement in this format: 

$FAB ...,CHAN_M0DE = access.mode,... 

From a high-level language, refer to your documentation as to how (and if) 
you can directly access VAX RMS fields and then incorporate the appropriate 
channel access mode expression into the appropriate language statement. 

5.8 FAB$I_CTX 

The user context (CTX) field allows you to convey user information to a 
completion routine in your program. This field contains a user-specified 
value, up to 4 bytes long, and is intended solely for your use. VAX RMS 
never uses it for record management activities. This field corresponds to the 
FDL attribute FILE CONTEXT. 

5.9 FAB$W_DEQ 

The default file extension quantity (DEQ) field specifies the number of blocks 
to be added when VAX RMS automatically extends the file. Automatic 
extension only applies to files that reside on disk devices and occurs whenever 
your program invokes a Put or Write service and the currently allocated file 
space is exhausted. When using a Put service, automatic file extension 
occurs when needed, regardless of the file organization. When using the 
Write service, automatic extension occurs only for sequential files (indexed 
and relative files require the Extend service to extend file allocation when 
using the Write service). This field corresponds to the FDL attribute FILE 
EXTENSION. 

This field contains a numeric value in the range 0 through 65,535, which 
is rounded up to the next cluster boundary. A large value results in fewer 
file extensions over the life of a file; a small value results in numerous file 
extensions over the life of a file. When a file has numerous file extensions 
that may be noncontiguous, this slows record access. 

For file creation, if you do not specify a value or specify 0, VAX RMS will use 
the default specified by the DCL command SET RMS_DEFAULT/EXTEND— 
QUANTITY. If this value is also 0, then VAX RMS uses the system default 
extension quantity specified by the SYSGEN parameter RMS_JEXTEND—SIZE. 
If this value is 0, then VAX RMS will compute the default value. 

When the value in this field, the value set by the SET RMS—DEFAULT 
/EXTEND—QUANTITY command, and the value of the SYSGEN parameter 
RMS—EXTEND—SIZE are all 0, VAX RMS calculates what is often a large 
value to minimize the number of extend operations that it must perform. At 
times, this value can exceed the available disk quota even though there is 
actually enough space for the file if only the required amount is used. You 
can use the DCL command SET RMS—DEFAULT/EXTEND—QUANTITY to 
limit (explicitly specify) the extension size to the recommended number of 
blocks. An appropriate size is the number of blocks specified as the cluster 
size for the device (set by the DCL command INITIALIZE/CLUSTER— 

SIZE). For large files on a volume where there is sufficient disk space, you 
should consider using a multiple of the cluster size to improve subsequent 
performance. 
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5.10 


When creating a new file, you can specify the extension quantity for the file 
by setting the desired value in the FAB$W_DEQ field before or after issuing a 
Create service. This value becomes a permanent attribute for the file. 

When processing an existing file, you can temporarily override the default 
extension quantity specified when the file was created. To do this, set the 
desired value before or after issuing the Open service. Once the file is closed, 
the default extension quantity reverts to the value set when the file was 
created. 

See the discussion under FAB$B_BKS for indexed files. 

Note that the use of an allocation control XAB will override the value in this 
field. See Section 8 for a detailed description of allocation control XABs. 


FAB$I_DEV 

The device characteristics (DEV) field allows your program to obtain the 
generic characteristics of the device containing the file. You can locate and 
test the various bits in the field using symbolic offsets. This is a binary 
options field set by VAX RMS when you issue an Open, Create, Display, or 
Parse service (this is set by the Parse service only if the NAM$V_SYNCFIK 
option in the NAM$B_NOP field is clear). 

Table 5-2 describes the bits in the device characteristics field. Each bit 
has its own symbolic bit offset and mask value. These definitions are 
made available to your program by referring to the $DEVDEF macro in 
SYS$LIBRARY:STARLET.MLB. The symbolic bit offset is formed by prefixing 
the characteristic name with DEV$V_. The mask value is formed by prefixing 

the characteristic name with DEV$M For example, the DEV$V_REC bit has 

a mask value of DEV$M_REC. 


Table 5-2 Device Characteristics 


Bit Offset 

Description 

DEV$V_ALL 

Device is allocated. 

DEV$V_AVL 

Device is available for use. 

DEV$V_CCL 

Carriage control device. 

DEV$V_CDP 

Device has dual access paths, one of which is a remote node 
using an MSCP server. 

DEV$V_CLU 

Device is available on a VAXcluster. 

DEV$V_DET 

Terminal device is detached. 

DEV$V_DIR 

Directory-structured device. 

DEV$V_DMT 

Device is marked for dismount. 

DEV$V_DUA 

Device has dual access paths, both of which use a disk class 
driver. 

DEV$V_ELG 

Device is error log enabled. 

DEV$V_FOD 

File-oriented device (disk and magnetic tape). 

DEV$V_FOR 

Device is mounted foreign (non-file-structured). 

DEV$V_GEN 

Device is a generic device. 

DEV$V_IDV 

Device can provide input. 
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Table 5-2 (Cont.) Device Characteristics 

Bit Offset Description 


DEV$V_MBX 

DEV$V_MNT 

DEV$V_NET 

DEV$V_ODV 

DEV$V_OPR 

DEV$V_RCK 

DEV$V_RCT 

DEV$V_REC 


DEV$V_RND 

DEV$V_RTM 

DEV$V_RTT 

DEV$V_SDI 

DEV$V_SHR 

DEV$V_SPL 

DEV$V_SQD 

DEV$V_SWL 

DEV$V_TRM 

DEV$V_WCK 


Device is a mailbox. 

Device is currently mounted. 

Network device. 

Device can accept output. 

Device has been enabled as an operator console terminal. 

Device has read-check enabled. 

Disk device is a RA80, RA81, or RA60 type device. 

Record-oriented device (terminal, mailbox, line printer, for 
example). If field is 0, device is assumed to be block-oriented 
(disk device or magnetic tape device). All record-oriented 
devices are considered sequential in nature. 

Device is random access in nature (disk). 

Device is real-time in nature; not suitable for use by VAX RMS. 
Terminal device is a remote terminal (DCL command SET HOST). 
Single directory device (master file directory only). 

Sharable device. 

Device is being spooled. 

Sequential block-oriented device (magnetic tape). 

Device is currently software write locked. 

Terminal device. 

Device has write-check enabled. 


For DECnet operations, this field represents the actual characteristics of the 
target device when a Create, Open, or Display service is invoked. It is not 
filled in when when a Parse service is invoked using a file specification that 
contains a node name. 


5.11 FAB$L_DNA 


The default file specification string address (DNA) field provides the address 
of a file specification string VAX RMS will use to apply defaults for any 
missing components of the file specification. This field works with the 
FAB$B_DNS field, which initializes the default file specification string size, 
to provide a default file specification string. Defaults are applied after VAX 
RMS examines the primary file specification string that the FAB$L_FNA field 
(described below) points to. This field and the FAB$B_DNS field correspond 
to the FDL attribute FILE DEFAULT-NAME. 

The FAB$L_DNA field contains the symbolic address of a default file 
specification string, which is an ASCII string containing one or more 
components of a file specification. The components in the string must be 
in the order in which they would occur in a complete file specification. 

The default file specification string is used primarily when accepting file 
specifications interactively; normally, file specifications known to a user 
program are specified completely in the FAB$L_FNA and FAB$B_FNS fields. 
You can specify defaults for one or more of the following file specification 
components: 
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• Node 

• Device 

• Directory 

• File name 

• File type 

• File version number 

The default file specification string is used only if components are missing 
from the string whose address is stored in the FAB$L_FNA field and those 
components are present in the default file specification string. 

If you use VAX MACRO, you can use the DNM keyword to specify the 
FAB$L_DNA and FAB$B_DNS fields. 


5.12 FAB$B_DNS 


The default file specification string size (DNS) field indicates the size, in 
bytes, of the string whose address is contained in the FAB$L_DNA field. 
This field contains a numeric value in the range 1 to 255. This field and the 
FAB$L_DNA field correspond to the FDL attribute FILE DEFAULT-NAME. 


5.13 FAB$B_FAC 


The file access (FAC) field defines the type of record operations that the 
program will perform using the specified file. VAX RMS uses this information 
to determine whether file access can be granted to the program. This field 
corresponds to the FDL primary attribute ACCESS. 

The FAB$B_FAC field is a binary options field in which each type of VAX 
RMS record operation to be performed by this program has a corresponding 
bit assignment. You can specify multiple types of record operations (multiple 
bits can be set). Options are identified by mnemonics. Each option in the 
FAB$B_FAC field has its own symbolic bit offset and mask value. For 
example, the GET option has a symbolic bit offset of FAB$V_GET and a mask 
value of FAB$M_GET. 

When opening a file, VAX RMS examines the FAB$B_FAC field to determine 
what type of record access operations your program will perform. VAX RMS 
then compares the FAB$B_FAC field with the FAB$B_SHR field of the first 
program that was granted access (the initial accessor) to determine whether 
or not access can be granted to the program. Access is granted if the FAB$B_ 
FAC field values of the subsequent accessor have the same values or a subset 
of the values specified in the FAB$B_SHR field of the initial accessor. For 
example, if the initial accessor set the FAB$B_FAC field FAB$V_GET option 
and the FAB$B_SHR field FAB$V_SHRGET option, only read access can be 
granted to subsequent file accessors. If the initial accessor set one or more 
FAB$B_SHR options, such as FAB$V_SHRGET and FAB$V_SHRPUT, other 
programs can access the file if both of the following conditions are met: 

1 The FAB$B_FAC options set by the other programs match or are a 

subset of the FAB$B_SHR options set by the initial accessor. If the initial 
accessor set FAB$B_SHR options FAB$V_SHRGET and FAB$V_SHRPUT, 
subsequent programs would need to set FAB$B_FAC options FAB$V_ 
GET, FAB$V_PUT, or both FAB$V_GET and FAB$V_PUT. 
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2 The FAB$B_SHR options set by the other programs match or are a 
superset of the FAB$B_FAC field options set by the initial accessor. If 
the initial accessor set the FAB$B_FAC option FAB$V_GET, subsequent 
programs would need to set FAB$B_SHR option FAB$V_SHRGET and 
any other options required for the application. 

If your program is the first program to access the file, file access is always 
granted. VAX RMS also examines the FAB$B_SHR field to determine what 
types of operations your program will allow other programs to perform. 

After you gain file access, VAX RMS compares your FAB$B_SHR field to the 
FAB$B_FAC fields of other programs requesting file access. 

After you open a file, VAX RMS rejects any operation that your program 
attempts if the operation was not specified in the FAB$B_FAC field when you 
issued an Open or Create service for the file. 

If your program will issue any of the following VAX RMS services below, 
you must specify them by setting the FAB$B_FAC field for the appropriate 
operation. 

• Delete 

• Extend 

• Find 

• Get 

• Put 

• Read 

• Space 

• Truncate 

• Update 

• Write 

The FAB$B_FAC field options are listed below. 

Options 

FAB$V_BIO 

Used for block I/O operations involving a Read or Write service, with the 
FAB$V_GET and FAB$V_PUT access options, respectively, and also with a 
Space service. Furthermore, specifying block I/O prohibits the use of any 
record I/O operations (such as the Get, Put, Update, Delete, or Truncate 
services). 

This option corresponds to the FDL attribute ACCESS BLOCK_IO. 

FAB$V_BRO 

Specifies that either block or record I/O will be used, to be specified at 
connect time in the RAB$V_BIO bit in the RAB. For additional information, 
see Section 4.8.2 under the discussion of block I/O and Section 7.19. 

This option corresponds to the FDL attribute ACCESS RECORD_IO. 

FAB$V_DEL 

Allows the Delete service (or the equivalent VAX language statement that 
deletes a record). This option applies only to relative and indexed files. 
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This option corresponds to the FDL attribute ACCESS DELETE. 

FAB$V_GET 

Allows the Get or Find service (or the equivalent VAX language statement 
that reads a record). This option is the default when you are opening this 
file and either the FAB$B_FAC field is not specified or the FAB$V_DEL, 
FAB$V_UPD, or FAB$V_TRN options are set in the FAB$B_SHR field. If you 
set FAB$V_GET and set either FAB$V_BIO or FAB$V_BRO, you can perform 
the Read service. 

This option corresponds to the FDL attribute ACCESS GET. 

FAB$V_PUT 

Allows a Put or Extend service (or the equivalent VAX language statement 
that writes a record or extends a file). This option is the default if you 
are creating this file. If you set FAB$V_PUT and set either FAB$V_BIO or 
FAB$V_BRO in the FAB$B_FAC field, you can perform the Write service. 

This option corresponds to the FDL attribute ACCESS PUT. 

FAB$V_TRN 

Allows a Truncate service (or the equivalent VAX language statement that 
truncates a file). Also allows use of the RAB$L_ROP truncate-on-put 
(RAB$V_TPT) option with the Put and Write service. This option applies 
only to sequential files. 

This option corresponds to the FDL attribute ACCESS TRUNCATE. 

FAB$V_UPD 

Allows an Update or Extend service (or the equivalent VAX language 
statement that rewrites a record or extends a file). Also allows use of the 
RAB$L_ROP update-if (RAB$V_UIF) option for the Put service. 

This option corresponds to the FDL attribute ACCESS UPDATE. 

5.14 FAB$L. 

_FNA 

The file specification string address (FNA) field works with the FAB$B_FNS 
field to specify the primary file specification of the file to be processed. If this 
string does not contain all the components of a full file specification, VAX 
RMS will use the defaults supplied in the default file specification string (see 
FAB$L_DNA and FAB$B_DNS). If no default string is present or if the file 
specification is still incomplete, VAX RMS provides additional defaults. This 
field and the FAB$B__FNS field correspond to the FDL attribute FILE NAME. 

This field contains the symbolic address of a file specification string, which 
is an ASCII string containing one or more components of a file specification. 
This field is used as input by many file-processing services. To obtain the file 
specification returned by VAX RMS after it translates any logical names and 
applies defaults, a NAM block must be present (see FAB$L_NAM). 

If you use VAX MACRO, you can use the FNM keyword to specify the 
FAB$L _FNA and FAB$B_FNS fields. 


5-11 








File Access Block (FAB) 

FAB$B_FNS 


5.15 FAB$B_FNS 

The file specification string size (FNS) field specifies the size, in bytes, of the 
ASCII file specification string, whose address is contained in the FAB$L_FNA 
field. This field contains a numeric value in the range of 0 through 255. This 
field and the FAB$L_FNA field correspond to the FDL attribute FILE NAME. 


5.16 FAB$L_FOP 

FAB$L _FOP is the symbolic offset value for the FAB's file-processing options 
(FOP) field. This field specifies which of the various optional file operations 
are to be implemented for the program and corresponds to the FDL primary 
attribute FILE. 

The FOP is a 32-bit field in which each file-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple 
bits can be set), when applicable. Each option has a unique symbolic offset 
value and mask value but you need only specify the appropriate 3-letter 
mnemonic when coding a function. For example, the spool-file-on-close 
option has a symbolic offset value of FAB$V_SPL but to specify the option, 
you use the following MACRO statement: 

FOP=SPL 

As detailed in the appropriate descriptions, the only file-processing option 
bits that may be affected by VAX RMS services are the FAB$V_CBT, FAB$V_ 
CTG, FAB$V_RCK, and FAB$V_WCK bits. 

This section presents the file-processing options alphabetically within the 
various functional categories, of which there are seven: 

• Allocation and extension options 

• Performance options 

• Reliability options 

• File name parsing modifiers 

• File disposition options 

• Magnetic Tape Processing options 

• Nonstandard processing options 

Table 5-3 lists each of the options alphabetically by category. 


Table 5-3 File Processing Options 

Option 

Allocation and extension options 
Contiguous best try 
Contiguous allocation 
Truncate at end of file 


Symbolic Offset 


FAB$V_CBT 

FAB$V_CTG 

FAB$V_TEF 
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Table 5-3 (Cont.) File Processing Options 


Option 

Symbolic Offset 

Performance Options 

Deferred write 

FAB$V_DFW 

Sequential only 

FAB$V_SQO 

Reliability Options 

Read-check 

FAB$V_RCK 

Write-check 

FAB$V_WCK 

File name parsing modifiers 

Create-if 

FAB$V_CIF 

Maximum version number 

FAB$V_MXV 

Use NAM block inputs 

FAB$V_NAM 

Output file parse 

FABSV—OFP 

Supersede existing file 

FAB$V_SUP 

File disposition options 

Delete on Close 

FAB$V_DLT 

Submit command file on Close 

FAB$V_SCF 

Spool file on Close 

FAB$V_SPL 

Temporary marked for delete 

FAB$V_TMD 

Temporary file 

FAB$V_TMP 

Magnetic Tape Options 

Do not set to EOF 

FAB$V_NEF 

Current position 

FAB$V_POS 

Rewind file on Close 

FAB$V_RWC 

Rewind file on Open 

FAB$V_RWO 

Nonstandard Options 

Non-file-structured 

FAB$V_NFS 

User file open 

FAB$V_UFO 


Allocation and Extension Options 
FAB$V_CBT 

Contiguous best try; indicates that the file is to be allocated contiguously 
on a "best effort" basis. It is input to the Create service and output from 
the Open service to indicate the file status. Note that the FAB$V_CBT bit 
remains set only if allocation using one, two, or three extents is actually 
performed. That is, the FAB$V_CBT bit is switched off before the return from 
the Create service unless VAX RMS can allocate the file within three extents. 
The FAB$V_CBT option overrides the FAB$V_CTG option. Note that this 
option is ignored if multiple areas are defined for an indexed file. This option 
corresponds to the FDL attribute FILE BEST_TRY_CONTIGUOUS. 
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FAB$V_CTG 

Contiguous; indicates that the space for the file is to be allocated contiguously. 
If this cannot be done, the operation fails. It is input to the Create service 
and is output by the Open service to indicate the status of the file. Note 
that this option is ignored if multiple areas are defined for an indexed file. 
The FAB$V_CBT option overrides the FAB$V_CTG option. This option 
corresponds to the FDL attribute FILE CONTIGUOUS. 

FAB$V_TEF 

Truncate at end of file; indicates that unused space allocated to a file is to be 
deallocated on a Close service. The FAB$V_TEF option applies to sequential 
files only. This option corresponds to the FDL attribute FILE TRUNCATE— 
ON-CLOSE. 

Performance Options 
FAB$V_DFW 

Deferred write; indicates that writing back to the file of modified I/O buffers 
is to be deferred until the buffer must be used for other purposes. This option 
applies to relative files, indexed files and sequential files opened for shared 
access. This option corresponds to the FDL attribute FILE DEFERRED- 
WRITE. This option is not supported for DECnet operations; it is ignored. 

FAB$V_SQO 

Sequential only; indicates that the file can be processed only in a sequential 
manner, permitting certain processing optimizations. Any attempt to perform 
random access will result in an error. The FAB$V_SQO option is input to the 
Create and Open services. This option corresponds to the FDL attribute FILE 
SEQUENTIAL -ONLY. 

Note: For DECnet operations, this option enables file transfer mode for Get, Put, 
Read, and Write services. File transfer mode is a Data Access Protocol 
(DAP) feature that allows several records to be transferred in a single 
network I/O operation to maximize throughput for single direction, 
sequential access file transfer. 

Reliability Options 
FAB$V_RCK 

Read-check; specifies that transfers from disk volumes are to be checked by a 
read-compare operation, which effectively doubles the amount of disk I/O at 
some increase in reliability. This option is an input to the Open and Create 
services. If FAB$V_RCK is set, then checking is performed for the duration 
of the access. The FAB$V_RCK option is also an output of the Open service, 
which indicates the default for the file. This option is not available for RX01 
and RX02 devices, or for any device that has been mounted using the DCL 
command MOUNT/FOREIGN. This option corresponds to the FDL attribute 
FILE READ-CHECK. 

FAB$V_WCK 

Write-check; indicates that transfers to disk volumes are to be checked by a 
read-compare operation. The FAB$V_WCK option is similar to the FAB$V_ 
RCK option. This option is not available for RX01 and RX02 devices, or 
for any device that has been mounted using the DCL command MOUNT 
/FOREIGN. This option corresponds to the FDL attribute FILE WRITE- 
CHECK. 
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File Name Parsing Modifiers 
FAB$V_CIF 

Create-if nonexistent; opens an already existing file if it exists. If the file does 
not exist, it is created and the alternate success status RMS$_CREATED is 
returned to indicate that the file was created, not just opened. The FAB$V_ 
CIF option is input only to the Create service and overrides the FAB$V_SUP 
option. When the create-if option is used with a search list logical name and 
the file is not found in any of the file specifications supplied using the search 
list, the file is created using the file specification from the first element of the 
search list. This option corresponds to the FDL attribute FILE CREATE _IF. 

FAB$V_MXV 

Maximize version number; indicates that the version number of the file should 
be the maximum of the explicit version number given in the file specification, 
or one greater than the highest version number for an existing file in the same 
directory with the same file name and file type. This option enables you to 
create a file with a specific version number (if the requested version number 
is greater than that of the existing file) or a file with a version number that 
is one higher than the existing file's version number. This option is used as 
input to the Create service only and it corresponds to the FDL attribute FILE 
MAXIMIZE —VERSION (default is "YES"). 

FAB$V_NAM 

Use NAM block inputs; indicates that the NAM block whose address is 
contained in the FAB$L_NAM (name block address) field will provide the 
device, file, and/or the directory identification when a file is being opened, 
closed, or erased (deleted) If a file is being created, the field specifies the 
device and directory identification. This option has no corresponding FDL 
attribute and it is not supported for DECnet operations. See Section 6 for 
further details. 

FAB$V_OFP 

Output file parse; specifies that related file resultant file specification strings, if 
used, are to provide directory, file name, and file type defaults only (requires 
NAM block). This option corresponds to the FDL attribute FILE OUTPUT— 
FILE—PARSE. 

FAB$V_SUP 

Supersede existing file; allows an existing file to be superseded on a Create 
service by a new file of the same name, type, and version. The FAB$V_CIF 
and the FAB$V_MXV option take precedence over the FAB$V_SUP option. 
This option corresponds to the FDL attribute FILE SUPERSEDE. 

File Disposition Options 
FAB$V_DLT 

Delete file on Close; indicates that the file will be deleted when closed. This 
option may be specified for the Create, Open, or Close services. However, 
if you set the bit when you create or open a file, VAX RMS deletes the file 
when you close it, irrespective of the state of the bit when you invoke the 
Close service. You can specify the FAB$V_DLT option with the FAB$V_SCF 
or FAB$V_SPL option. This option corresponds to the FDL attribute FILE 
DELETE _ON -CLOSE. 


5-15 





File Access Block (FAB) 

FAB$I_FOP 


FAB$V_SCF 

Submit command file on Close; indicates that the file is to be submitted as a 
batch-command file to the process-default batch queue (SYS$BATCH) when 
the file is closed. This option can be specified for the Create, Open, and Close 
services. However, if you set the bit when you create or open a file, VAX 
RMS submits the file to SYS$BATCH when you close it, irrespective of the 
state of the bit when you invoke the Close service. The FAB$V_SCF option 
applies to sequential files only and it corresponds to the FDL attribute FILE 
SUBMIT—ON —CLOSE. 

FAB$V_SPL 

Spool file on Close; indicates that the file is to be spooled to the process- 
default print queue (SYS$PRINT) when the file is closed. This option can 
be specified for the Create, Open, or Close services. However, if you set the 
bit when you create or open a file, VAX RMS spools the file to SYS$PRINT 
when you close it, irrespective of the state of the bit when you invoke the 
Close service. The FAB$V_SPL option applies to sequential files only and it 
corresponds to the FDL attribute FILE PRINT—ON—CLOSE. 

FAB$V_TMD 

Temporary file marked for delete; indicates that a temporary file is to be 
created but will be deleted when the file is closed. This option is input only 
to the Create service. The FAB$V_TMD option takes precedence over the 
FAB$V_TMP option. This option corresponds to the FDL attribute FILE 
TEMPORARY. 

FAB$V_TMP 

Temporary file; indicates that a temporary file is to be created and retained, 
but that no directory entry will be made for it. This option is used solely 
as input to the Create service. If you have a NAM block, you are given 
the file identification (FID) of the file which you can use to reopen the file. 

If you do not have a NAM block or if you do not save the FID, the file 
becomes inaccessible once it is closed. The FAB$V_TMD option overrides 
the FAB$V_TMP option. This option corresponds to the FDL attribute FILE 
DIRECTORY-ENTRY ("NO" means this bit is set). 

Magnetic Tape Processing Options 
FAB$V—NEF 

Do not position to end of file; inhibits the positioning to the end of a file 
when a tape file is opened and the FAB$B_FAC (file access) field indicates 
a Put service. This option corresponds to the FDL attribute FILE MT_NOT— 
EOF. 

FAB$V_POS 

Current position; indicates that the magnetic tape volume set should be 
positioned immediately after the most recently closed file when the next file 
is created. The FAB$V_RWO option overrides the FAB$V_POS option and it 
corresponds to the FDL attribute FILE MT_CURRENT—POSITION. 

FAB$V_RWC 

Rewind file on Close; specifies that the magnetic tape volume will be rewound 
when the file is closed. This option can be specified for the Close, Create, 
or Open services. This option corresponds to the FDL attribute FILE MT_ 
CLOSE-REWIND. 
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FAB$V_RWO 

Rewind file on Open; specifies that the magnetic tape volume will be 
rewound before the file is opened or created. The FAB$V_RWO option 
takes precedence over the FAB$V_POS option. This option corresponds to 
the FDL attribute FILE MT_OPEN-REWIND. 

Nonstandard Processing Options 
FAB$V_NFS 

Non-file-structured; indicates (on an Open or Create service) that the volume 
is to be processed in a non-file-structured manner. This option allows the use 
of volumes created on non-DIGITAL systems and it corresponds to the FDL 
attribute FILE NON—FILE—STRUCTURED. This option is not supported for 
DECnet operations. 

FAB$V_UFO 

User file open; indicates that VAX RMS operations for this file are limited to 
opening it or creating it. To perform additional processing of the file. Invoke 
the SYS$QIO system service using the channel number returned by VAX 
RMS in the status value field (FAB$L_STV). This channel will be assigned 
in the access mode of the caller unless otherwise specified by the FAB$V— 
CHAN-MODE bits. 

If you specify this option, you must set the FAB$B_SHR field FAB$V_UPI 
bit option unless the file is not shared (FAB$B_SHR field FAB$V_NIL option 
is set). For the Create service, the end-of-file mark will be set to the end of 
the block specified in the FAB$L_ALQ field on input. For either the Open 
or Create services, the FAB$W_IFI field is set to 0 on return to indicate that 
VAX RMS cannot perform any more operations on the file. If you set the 
FAB$V_UFO option with the Open or Create service, the channel needs only 
to be deassigned when you are finished with the file. A Close service is not 
required. This option corresponds to the FDL attribute FILE USER—FILE- 
OPEN and it is not supported for DECnet operations. 


5.17 FAB$B_FSZ 

The fixed-length control area size (FSZ) field is used only for variable with 
fixed-length control (VFC) records. When you create a file with this type of 
record, you must set the value for the fixed-control area before you issue the 
Create service. When you open an existing file that contains variable with 
fixed control records, VAX RMS sets this field equal to the value specified 
when the file was created. The FAB$B_FSZ field is not applicable to indexed 
files. This field corresponds to the FDL attribute FILE CONTROL—FIELD- 
SIZE. 

This field contains a numeric value in the range of 1 to 255 that indicates, in 
bytes, the size of the fixed control area; the default size is 2 bytes. If you do 
not specify a value or specify 0, then the default size is used. 
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5.18 FAB$W_GBC 


The global buffer count (GBC) field indicates the requested number of global 
buffers for a file. This field contains a numeric value in the range of 0 to 
32,767; the default is 0. This field corresponds to the FDL attribute FILE 
GLOBAL _BUFFER_COUNT. 

Global buffers support sharing of I/O buffers by more than one process. 

The use of global buffers can minimize I/O operations for a shared file, thus 
reducing record access time at the cost of using additional system resources. 
VAX RMS is able to locate requested records (or blocks) in the global buffers 
associated with this file, which it can read directly from memory, eliminating 
much I/O. However, since global buffers use global sections, the value 
contained in FAB$W_GBC is limited by systemwide restrictions on resources 
determined by the system parameters GBLSECTIONS (number of global 
sections), GBLPAGES (number of global page table entries), GBLPAGFIL 
(number of systemwide pages allowed for global page-file sections, or scratch 
global sections), and RMS—GBLBUFQUO (total number of simultaneously 
active VAX RMS global buffers allowed for the system). 

If global buffers are specified for a file, global buffers are used instead of local 
(process) buffers, with the exception of deferred write operations (FAB$L_ 
FOP field FAB$V_DFW option). 

The value that is specified when the file is created will be returned in the 
FAB$W_GBC field as output from the Open service. This value is then used 
as input to the Connect service. 

If you wish to override the default value specified when the file was created, 
you can set a different value in the FAB$W_GBC field after opening the file 
but before invoking the Connect service. If you do not wish to use global 
buffers, you can clear the field before issuing the Connect service if the 
default value is not 0. 

If you modify the value in the FAB$W_GBC field that is returned from the 
Open service prior to the Connect service, this action will be meaningful to 
determine whether or not global buffers will be used for this process. 

If you wish to permanently change the default global buffer count value for 
the file, use the following DCL command: 

$ SET FILE file-spec /GLOBAL_BUFFERS=buffer-count 

If you wish to permanently clear the default global buffer count for a file, use 
the following DCL command: 

$ SET FILE file-spec /GL0BAL_BUFFERS=0 

You can also vary the number of global buffers used each time you process 
the file. If you choose this method, you change (or clear) the FAB$W_GBC 
field after you open the file, but before you issue the Connect service. In this 
case, the specified value will be assigned to the FAB$W__GBC field, or the 
FAB$W_GBC field will remain clear only for the current processing of the 
file; that is, you will not permanently alter the FAB$W_GBC field in the FAB. 
If no value is specified in the FAB$W_GBC field when the file is created, the 
default value will be 0. 

The number of global buffers for a file is determined by the first record stream 
to connect to the file (systemwide). If the file is already open and connected, 
then the number of global buffers is already set and modifications made 
before the Connect service are useful only to request that this process use (or 
not use) global buffers. 
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Note: To specify a read-only global buffer cache, the initial accessor must set 
the FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits on. 

You can use global buffers for all file organizations opened for shared record 
access. If the global buffer count is nonzero for the first process that connects 
to the file, then a temporary global section that is large enough to contain the 
specified number of buffers (as well as internal VAX RMS data structures) will 
be created and mapped. Subsequent processes that connect to the file will 
map this section, thus allowing multiple processes to reference a single set of 
one or more buffers without performing additional I/O operations. Thus, the 
first user to open the file requesting global buffers determines the number of 
the global buffers. 

This field is not supported for DECnet operations. 


5.19 FAB$W_IFI 


The internal file identifier (IFI) field is set by VAX RMS to associate the FAB 
with the corresponding internal file access block. VAX RMS sets this field on 
successful Create or Open services. It is then an input for subsequent Close, 
Connect, Display, and Extend services. The Close service deallocates the 
internal control structures and clears the FAB$W_IFI field. When the user file 
open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no internal 
structures are allocated on Create or Open services. Therefore, the FAB$W_ 
IFI field will remain cleared. There is no FDL equivalent for this field. 


5.20 FAB$V_UMM_MODE 

The logical name translation access mode (LNM_MODE) field lets you 
specify the access mode that VAX RMS will use to translate logical names 
during parsing. The FAB$V_LNM_MODE field is a 2-bit field that contains 
one of the following values: 

0 none 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 

3 User mode (PSL$C_USER) 

The default value is 0 (none), which VAX RMS interprets as user mode. 

There is no corresponding FDL equivalent for this field. The FAB$V_LNM_ 
MODE field is not supported for DECnet operations, and it is ignored during 
any DECnet remote file access. 


5.21 FAB$L_MRN 


The maximum record number (MRN) field applies only to relative files and 
indicates the highest record number that can be written to a file. This field 
corresponds to the FDL attribute FILE MAX_RECORD_NUMBER. 

This field contains a numeric value of the highest numbered record allowed 
in the file, in the range of 0 to 2,147,483,647, although the maximum value 
depends on the number of blocks on the device to be used. The default for 
this field is 0. 
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If you attempt to write (put) or retrieve (get) a record with a relative record 
number higher than the specified limit, an error will occur and VAX RMS 
will return a message indicating an invalid record number. If, however, you 
specify 0 for the FAB$L_MRN field, checking is suppressed. 

Note that VAX RMS does not maintain the relative record number of the 
highest existing record in the file. 


5.22 FAB$W_MRS 

The maximum record size (MRS) field defines the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size for relative files. This field corresponds to the FDL attribute 
RECORD SIZE. 

This field contains a numeric value in the range applicable to the file type 
and record format (see Table 5-4) that indicates the size of the records in the 
file, in bytes. This value specifies the number of bytes of data and does not 
include any control bytes associated with each record. 

For fixed-length records, the value represents the actual size of each record 
in the file. You must specify a size when you create a file with fixed-length 
records. 

For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size, except for the limitations listed in Table 5-4 and certain 
physical limitations. For magnetic tape files, a value of 0 sets an effective 
maximum record size that is equal to the block size minus 4. 

The size of variable-length records must conform to physical limitations. 

With indexed and relative files, for example, records may not cross bucket 
boundaries. If both the FAB$B_BKS and FAB$W_MRS fields are 0 (not 
specified) for an indexed file, VAX RMS attempts to calculate a reasonable 
bucket size, usually 2. Thus, if any record requires more than two buckets, 
you must explicitly specify the required value for the FAB$B_BKS or the 
FAB$W_MRS field. If FAB$B_BKS field is specified, the value should specify 
a bucket size large enough to exceed the longest possible record. 

For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 

For all relative files, the size is used to determine the size of the record cell in 
conjunction with the FAB$B_BKS field. You must specify the FAB$W_MRS 
field when you create a relative file. 

You specify a value when you invoke a Create service. VAX RMS returns the 
maximum record size when you invoke an Open service. 

Table 5-4 summarizes the maximum record size allowed for the various file 
and record formats. 
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Table 5-4 Maximum Record Size for File Organizations and 
Record Formats 


File Organization 

Record Format 

Maximum 

Record Size 

Sequential 

Fixed-length 

32,767 

Sequential (disk) 

Variable-length 

32,767 

Sequential (disk) 

VFC 

32,767-FSZ 1 

Sequential (disk) 

Stream 

32,767 

Sequential (disk) 

Stream-CR 

32,767 

Sequential (disk) 

Stream-LF 

32,767 

Sequential (ANSI Tape) 

Variable-length 

9,995 

Sequential (ANSI Tape) 

VFC 

9,995-FSZ 1 

Relative 

Fixed-length 

32,255 

Relative 

Variable-length 

32,253 

Relative 

VFC 

32,253-FSZ 1 

Indexed, Prolog 1 or 2 

Fixed-length 

32,234 

Indexed, Prolog 1 or 2 

Variable-length 

32,232 

Indexed, Prolog 3 

Fixed-length 

32,224 

Indexed, Prolog 3 

Variable-length 

32,224 


^he FSZ represents the size of the fixed control area of a record for the variable 
with fixed-control (VFC) record format. The FSZ is equal to the size, in bytes, for 
the fixed control area of VFC records. 


The length of the largest record in a sequential file on a disk device with variable 
or VFC record format is also maintained by VAX RMS and is available through the 
file header characteristics XAB (XAB$W_LRL field of XABFHC; see Section 10). 


For DECnet remote file access, the maximum record size is set by using 
the /NETWORK—BLOCK_COUNT=n qualifier to the SET RMS—DEFAULT 
command. DECnet remote file access can have record sizes as large as 
VAX RMS supports. The default number of blocks is equal to the SYSGEN 
parameter RMS_DFNBC, the default for which is 8 blocks (4096 bytes). 

For more information about the SET RMS—DEFAULT command, see the 
VAX/VMS DCL Dictionary. The SYSGEN parameters are detailed in the 
VAX/VMS System Generation Utility Reference Manual. 


5.23 FAB$I_NAM 

The name block address (NAM) field specifies the address of the NAM 
block used to invoke a file service, such as an Open or Create. The NAM 
block, described in Section 6, is required only in conjunction with the file 
specification processing services. But it can also be used with other services, 
typically to obtain a file specification string after all logical name translation is 
completed and all defaults applied. Note that the FAB$L_FOP option NAM 
must be specified for the NAM block to be used as input (see FAB$L_FOP). 
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5.24 FAB$B_ORG 


The file organization (ORG) field assigns the organization of the file. This 
field corresponds to the FDL attribute FILE ORGANIZATION. 

The FAB$B_ORG field is a keyword value field in which each file 
organization has a symbolic value. Options are identified using 3-letter 
mnemonics. Each option in the FAB$B_ORG field has its own symbolic 
constant value. For example, the relative (REL) file organization has a 
constant value of FAB$C_REL. 

You must set this field before you invoke a Create service. VAX RMS returns 
the contents of this field when you invoke an Open service. Here is a listing 
of the options and their meanings: 

• FAB$C_IDX — Indexed file organization 

• FAB$C_REL — Relative file organization 

• FAB$C_SEQ — Sequential file organization (default) 


5.25 FAB$B_RAT 


The record attributes (RAT) field indicates the type of record control 
information associated with each record in a file. This field corresponds 
to the FDL primary attribute RECORD. 

The FAB$B_RAT field is a binary options field in which each record attribute 
has a corresponding bit assignment. Options are identified by mnemonics. 
Each option in the field has its own symbolic bit offset and constant value. 
For example, the CR record attribute has a symbolic bit offset of FAB$V_CR 
and a mask value of FAB$M_CR. 

Only the FAB$V_BLK option can be paired with another option. You cannot 
use FAB$V_CR, FAB$V_FTN, and FAB$V_PRN together in any combination. 

For most VAX/VMS programs, the default value for this field is FAB$V_CR 
(carriage return). When you create your own file, however, the default value 
is 0. When creating a stream format file or any text file (a file containing 
ASCII text), it is recommended that you specify the FAB$V_CR option for the 
Create service. VAX RMS will set this field when you issue an Open service. 
When a process permanent file is accessed indirectly for output, the value 
in this field is always an input value. VAX RMS will automatically convert 
the records from the record attributes specified to the actual attributes of the 
process permanent file. 

Options 

FAB$V_BLK 

Applicable to sequential files only; Indicates that records are not permitted to 
cross block boundaries. 

This option corresponds to the FDL attribute RECORD BLOCK-SPAN. 

FAB$V_CR 

Indicates that each record is to be preceded by a line feed and followed by a 
carriage return when the record is written to a carriage control device such as 
a line printer or terminal. 
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This option corresponds to the FDL attribute RECORD CARRIAGE-. 
CONTROL CARRIAGE —RETURN. 

FAB$V_FTN 

Indicates that the first byte of each record contains a FORTRAN (ASA) 
carriage control character. 

This option corresponds to the FDL attribute RECORD CARRIAGE— 
CONTROL FORTRAN. Records are defined as follows: 


Byte 0 

Value 

(hex) 

ASCII 

Character 

Meaning 

0 

(null) 

Null carriage control (sequence: print buffer 
contents). 

20 

(space) 

Single-space carriage control (sequence: line 
feed, print buffer contents, carriage return). 

30 

0 

Double-space carriage control (sequence: line 
feed, line feed, print buffer contents, carriage 
return). 

31 

1 

Page eject carriage control (sequence: form 
feed, print buffer contents, carriage return). 

28 

+ 

Overprint carriage control (sequence: print 
buffer contents, carriage return). Allows 
double printing for emphasis. 

24 

$ 

Prompt carriage control (sequence: line feed, 
print buffer contents). 

Other values 


Same as ASCII space character: single-space 
carriage control. 


FAB$V_PRN 

Indicates print file format for variable with 2-byte fixed-length control records, 
where the fixed control area contains the carriage control specification. The 
first byte of the fixed control area constitutes a "prefix" area, and the second 
byte constitutes a "postfix" area, specifying carriage control to be performed 
before and after printing the record respectively. 

This option corresponds to the FDL attribute RECORD CARRIAGE— 
CONTROL PRINT. 

The coding scheme of both bytes is presented below (even though they are 
interpreted separately): 


Bit 7 

Bits 0-6 

Meaning 


0 

0 

No carriage control is specified. 

that is, NULL 

0 

1-7F 

Bits 0 through 6 are a count of 
followed by carriage return). 

new lines (line feeds 
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Bit 7 

Bit 6 

Bit 5 

Bits 0-4 

Meaning 

1 

0 

0 

0-1F 

Output the single ASCII control 
character specified by the 
configuration of bits 0 through 4 
(7-bit character set). 

1 

1 

0 

0-1F 

Output the single ASCII control 
character specified by the 
configuration of bits 0 through 

4 which are translated as ASCII 
characters 128 through 159 (8-bit 
character set). 

1 

1 

1 

0-1F 

Reserved. 


5.26 FAB$B_RFM 

The record format (RFM) field specifies the format for all the records in a file. 
This field corresponds to the FDL attribute RECORD FORMAT. 

The FAB$B_JRFM field is a keyword value field where each record format has 
a symbolic value. Options are identified by mnemonics. Each option has its 
own symbolic constant value. For example, the FIX (fixed) record format has 
a symbolic constant value of FAB$C_FIX; the STMCR record format has a 
constant value of FAB$C_STMCR. 

When you create the file, you must set this field before you invoke the Create 
service. VAX RMS returns the record format when you invoke an Open 
service. The record format options are described below. 

Options 

FAB$C_FIX 

Indicates fixed-length record format. 

This option corresponds to the FDL attribute RECORD FORMAT FIXED. 

FAB$C_STM 

Indicates stream record format. Records are delimited by FF, VT, LF, or CR 
LF. This format is supported for sequential files only. 

This option corresponds to the FDL attribute RECORD FORMAT STREAM. 

FAB$C_STMCR 

Indicates stream record format. Records are delimited by CR. This format is 
supported for sequential files only. 

This option corresponds to the FDL attribute RECORD FORMAT STREAM__ 
CR. 

FAB$C_STMLF 

Indicates stream record format. Records are delimited by LF. This format is 
supported for sequential files only. 

This option corresponds to the FDL attribute RECORD FORMAT STREAM— 
LF. 
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FAB$C_UDF 

Indicates undefined record format. The undefined record format is valid for 
sequential files only. This is the default value if the FAB is not initialized 
with a VAX MACRO $FAB macro. 

This option corresponds to the FDL attribute RECORD FORMAT 
UNDEFINED. 

FAB$C_VAR 

Indicates variable-length record format. For the VAX MACRO $FAB macro, 
this is the default value. 

This option corresponds to the FDL attribute RECORD FORMAT VARIABLE. 

FAB$C_VFC 

Indicates variable-length with fixed-length control record format. This format 
is not supported for indexed files. This option corresponds to the FDL 
attribute RECORD FORMAT VFC. 

If you intend to use stream record format, then specify the FAB$B_RAT 
FAB$V_CR record attribute (see FAB$B_RAT). 


5.27 FAB$B_RTV 


The retrieval window size (RTV) field specifies the number of retrieval 
pointers VAX RMS is to maintain in memory for the file. Retrieval pointers 
are stored in the file header and indicate the beginning of each extent 
associated with the file. If a file has been extended repeatedly, the extents 
may be scattered noncontiguously on the disk, requiring numerous retrieval 
pointers. When VAX RMS needs to access a new extent, it must first obtain 
the retrieval pointer for that extent. VAX RMS first looks for the retrieval 
pointer in the retrieval window, which contains the number of retrieval 
pointers specified by this field. If the retrieval pointer is not in the retrieval 
window, VAX RMS must first read the file header, causing an additional I/O 
operation. This field corresponds to the FDL attribute FILE WINDOW-SIZE. 

This field contains a numeric value in the range of 0 through 127, or 255. A 
value of 0 indicates that VAX RMS is to use the system default number of 
retrieval pointers. A value of 255 means to map the entire file, if possible. If 
you specify a value of 255 when creating a file, the initial number of retrieval 
pointers will be minimal; as records are added, however, the number of 
retrieval pointers will increase as the number of extents increases. The system 
resources required for retrieval windows are subtracted from the buffered 
I/O quota of the process. Values from 128 to 254 (inclusive) are reserved for 
future use. 

This field is not supported for DECnet operations; it is ignored. 
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5.28 FAB$I_SDC 

The secondary device characteristics (SDC) field is equivalent to the 
FAB$L_DEV field, except that secondary device characteristics refer to 
the intermediate device used for spooling or the logical link for DECnet 
operations. The FAB$L_SDC field is a binary options field whose bit 
definitions are the same as those defined for the FAB$L_DEV field (see 

Table 5-2). Like the FAB$L_DEV field, the bit definitions must first be 
made available to your program by referring to the $DEVDEF system macro 
definition; the values are set by certain VAX RMS services (see FAB$L__DEV 
for additional information). 

5.29 FAB$B_SHR 

The file sharing (SHR) field defines the type of record operations that the 
program will allow other programs sharing access to this file to perform. VAX 
RMS uses this information to determine whether file access can be granted to 
this program. VAX RMS supports file sharing for all file organizations. This 
field corresponds to the FDL primary attribute SHARING. 

The FAB$B_SHR field is a binary options field in which each type of VAX 
RMS record operation to be allowed by other programs has a corresponding 
bit assignment. You can specify multiple types of record operations (multiple 
bits may be set). 

Options are identified by symbolic bit offsets. Note that where this may 
be in conflict with the symbolic bit offsets in the FAB$B_FAC field, the 
letters SHR are prefixed to the mnemonic part of the symbol. For example, 
both the FAB$B__FAC and FAB$B_SHR fields have a bit that specifies the 
get record option. In the FAB$B_FAC field, this bit offset is assigned the 
symbol FAB$V_GET; in the FAB$B_SHR field, this bit is assigned the symbol 
FAB$V_SHRGET. 

Note that the letters SHR in the mnemonic part of the bit offset symbol 
may be omitted by VAX MACRO programs. Thus, the GET option, which 
is common to the FAB$B_FAC and FAB$B_SHR fields, has a symbolic 
bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but 
VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_ 
GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_ 
SHRDEL, and FAB$V_SHRUPD options. 

The way in which VAX RMS uses the file access (FAB$B_FAC) field and file 
sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC 
field. 

The following list includes descriptions of the sharing options: 

Options 

FAB$V_MSE 

Allows multistream access and is relevant for record operations only. You 
must specify FAB$V_MSE whenever you wish to issue Connect services for 
multiple RABs for this FAB. This option is available for all file organizations 
and corresponds to the FDL attribute SHARING MULTISTREAM. 
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Note that if you specify the FAB$V__MSE and FAB$V_BRO options, you must 
set the FAB$V_UPI bit regardless of the other sharing bits. 

Note: To specify a read-only global buffer cache, the initial accessor must set 
the FAB$B_SHR field FAB$V_SHRGET and FAB$V__MSE bits on. 

This option is not supported for DECnet operations; an error is returned. 

FAB$V_NIL 

Prohibits any type of file sharing by other users. (If specified along with other 
options, FAB$V_NIL takes precedence.) 

This option corresponds to the FDL attribute SHARING PROHIBIT. 

FAB$V_SHRPUT 

Allows other users to write records to the file or to extend the file. 

This option corresponds to the FDL attribute SHARING PUT. 

FAB$V__SHRGET 

Allows other users to read the file. 

This option corresponds to the FDL attribute SHARING GET. 

FAB$V_SHRDEL 

Allows other users to delete records from the file. 

This option corresponds to the FDL attribute SHARING DELETE. 

FAB$V_SHRUPD 

Allows other users to update records that currently exist in the file or extend 
the file. 

This option corresponds to the FDL attribute SHARING UPDATE. 

FAB$V_UPI 

This option is set in combination with the FAB$V_SHRPUT, FAB$V__ 
SHRGET, FAB$V_SHRUPD, FAB$V_SHRDEL, and/or FAB$V_MSE options 
to permit one or more writers to access a shared file. Usually, this option is 
used for a file that is open for block I/O (FAB$V_BIO or FAB$V_BRO). If the 
FAB$L_FOP field FAB$V_UFO option is set, this option must be set. The 
programmer assumes the responsibility for any required interlocking. 

This option corresponds to the FDL attribute SHARING USER_INTERLOCK. 

Note that if you do not specify a value, VAX RMS enters a value of 0 in the 
FAB$B_SHR field. Defaults apply as follows: 

• If the FAB$B_FAC field is set or defaulted to FAB$V_GET, the FAB$B_ 
SHR field defaults to FAB$V_SHRGET. 

• If the FAB$B_FAC field is set or defaulted to either FAB$V_PUT, FAB$V_ 
DEL, FAB$V_UPD, or FAB$V_TRN, the FAB$B_SHR field defaults to 
FAB$V_NIL. Thus, write-sharing must be explicitly requested using the 
FAB$B_SHR field (because it is not the default). 

See the Guide to VAX/VMS File Applications for additional details on file 
sharing. 
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5.30 

FAB$I_STS 

The completion status code (STS) field is set by VAX RMS with success or 
failure codes before control is returned to your program (except for a subset 
of errors, as detailed in Section 2.4). Register 0 will contain the same status. 
Potential error codes for specific services are listed under their descriptions 
in Part III. Status codes are discussed further in Part I. 

5.31 

FAB$I_STV 

The status value (STV) field is set by VAX RMS and, on the basis of the 
type of operation performed and the contents of the completion status code 
(FAB$L__STS) field, communicates additional completion information to your 
program. See Part III for the instances when VAX RMS uses the status value 
field. 

5.32 

FAB$I_XAB 



The extended attribute block address (XAB) field specifies the XAB, or first of 
a series of XABs, that you want to use when performing a file service, such as 
an Open or Create, on a file. 

This field contains a symbolic address of an XAB control block. A value of 0 
(the default) indicates no XABs for the file. 

For some operations, you must associate extended attribute blocks (XABs) 
with a FAB to convey additional attributes about a file. (See Part I for a 
description of an XAB.) The FAB$L_XAB field can contain the symbolic 
address of the first associated block (of a potential chained list of such blocks) 
for the file. 

VAX RMS uses the XAB values for different VAX RMS operations as follows: 

1 If you specify an XAB for either an Open or Display service, VAX RMS 
returns the attributes for the file to the XAB. 

2 If you specify an XAB for a Create, Close, or Extend service, VAX RMS 
uses the XAB as input to those functions. 
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6 Name Block (NAM) 


The name (NAM) block provides additional fields for extended file 
specification use, including parsing and obtaining the actual file specification 
used for a file operation. 


6.1 Summary of Fields 

The symbolic offset, size, and a brief discussion of each NAM block field are 
presented in Table 6-1. 


Table 6-1 NAM Block Fields 


Field Offset 

Size 

(bytes) 

Description 

NAMSB-BID 1 

1 

Block identifier 

NAMSB—BLN 1 

1 

Block length 

NAM$B_DEV 2 

1 

Device string length 

NAM$L_DEV 2 

4 

Device string address 

NAM$W_DID 2 

6 

Directory identification 

NAM$B_DIR 2 

1 

Directory string length 

NAM$L_DIR 2 

4 

Directory string address 

NAM$T_DVI 2 

16 

Device identification 

NAM$L_ESA 

4 

Expanded string area address 

NAM$B_ESL 2 

1 

Expanded string length 

NAM$B_ESS 

1 

Expanded string area size 

NAM$W_FID 2 

6 

File identification 

NAM$L_FNB 2 

4 

File name status bits 

NAM$B_NAME 2 

1 

File name string length 

NAM$L_NAME 2 

4 

File name string address 

NAM$B_NODE 2 

1 

Node name string length 

NAM$L_NODE 2 

4 

Node name string address 

NAM$B_NOP 

1 

Name block options 

NAM$I_RLF 

4 

Related file NAM block address 

NAM$I_RSA 

4 

Resultant string area address 

NAM$B_RSL 2 

1 

Resultant string length 

NAM$B_RSS 

1 

Resultant string area size 

NAM$B_TYPE 2 

1 

File type string length 


Statically initialized field (by the VAX MACRO $NAM macro) to identify this 
control block as a NAM. 

2 Field cannot be initialized by the VAX MACRO $NAM macro. 
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Table 6-1 (Cont.) NAM Block Fields 


Field Offset 

Size 

(bytes) 

Description 

NAM$I_TYPE 2 

4 

File type string address 

NAM$B_VER 2 

1 

File version string length 

NAM$I_VER 2 

4 

File version string address 

NAM$I_WCC 2 

4 

Wildcard context 

2 Field cannot be initialized by the VAX MACRO $NAM macro. 


Each NAM block field is described below. The NAM block fields have no 
corresponding FDL equivalents. However, if your application requires the 
presence of a NAM block, consider using the $NAM VAX MACRO macro (or 
equivalent) perhaps in a USEROPEN or a USERACTION routine. 

Unless indicated otherwise, each field is supported for DECnet operations 
when the remote node is a VAX/VMS system. Note that the words "DECnet 
operations" in the following descriptions refer to remote file operations 
between two VAX/VMS systems. See the VAX/VMS Networking Manual for 
information about the support of VAX RMS options for remote file access to 
non-VAX/VMS systems. 

Depending on the VAX RMS services to be used, the user may need to 
allocate program storage for the expanded string and the resultant string. The 
expanded string is used for the Parse service to pass certain information to 
the Search service related to wildcards (or search lists). For certain other VAX 
RMS file services, the expanded string is used as a work area by VAX RMS as 
it applies defaults to create a resultant string. You can use the resultant string 
with VAX RMS file services to provide the file specification that results from 
the translation of logical names and the application of defaults. Typical uses 
of the resultant string include showing the resulting file specification after a 
partial file specification is entered by a terminal user, for error reporting, and 
for logging the progress of a program. 

To request use of the expanded and/or resultant strings, you must indicate 
to VAX RMS the address and size of the user-allocated buffer to receive 
the string. The expanded string is indicated by the NAM$L_ESA and 
NAM$B_ESS fields; the resultant string is indicated by the NAM$L_RSA 
and NAM$B_RSS fields. When it fills in the expanded or resultant fields, 
VAX RMS returns the actual length of the returned string in the NAM$B_ESL 
or NAM$B_RSL fields. 

The format and arguments of the VAX MACRO $NAM and $NAM_STORE 
macros are defined in Appendix B. 
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6.2 File Specification Component Descriptors 

For each element of the fully qualified file specification returned in the 
expanded or resultant string fields in the NAM block, VAX RMS returns a 
descriptor in the NAM block. Two fields describe the element: a 1-byte size 
field and a 4-byte (longword) address field. The fields of these descriptors are 
described as one of the following: 

NAM$B_xxx (size field of xxx) 

NAM$I xxx (address field of xxx) 

Each descriptor is summarized below. 

Descriptor 

NAM$B_NODE, NAM$I_NODE 

Node name descriptor, including access control string and double colon (::) 
delimiter. 

NAM$B_DEV, NAM$I_DEV 

Device name descriptor, including colon (:) delimiter. 

NAM$B_DIR, NAMSl_DIR 

Directory list descriptor, including brackets ([ and ] or < and > ). 

NAM$B_NAME, NAM$I_NAME 

File name descriptor or, if the file specification following a node name is 
within quotation marks ("file"), a quoted string descriptor. 

NAM$B_TYPE, NAM$I_TYPE 

File type descriptor, including period (.) delimiter. 

NAM$B_VER, NAM$L_VER 

File version number descriptor, including semicolon (;) or period (.) 
delimiter. 

These descriptors are returned, enabling the program to extract a particular 
component from the resultant string without having to parse the resultant 
or expanded string. The entire resultant or expanded string, including 
delimiters, is described by the various component descriptors. If the value in 
the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L _ 
RSA field. If the value in the NAM$B_RSL field is 0 and the value in the 
NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA 
field. In all other cases, they are undefined. 

As an example, a resultant file specification and its file specification 
component descriptors are shown below. 

_NODE"TEST password"::WORK_DISK:[TEST.TEMP]FILE.DAT;3 


NODE 

- 

_NODE"TEST password 

DEV 

- 

WORK_DISK: 

DIR 

- 

[TEST.TEMP] 

NAME 

- 

FILE 

TYPE 

- 

.DAT 

VER 

- 

;3 


You can use the field descriptors individually or collectively to describe 
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sections of the resultant or expanded string. For example, if you wish to use 
the file name and file type fields, you would use NAM$L_NAME for the 
starting address and NAM$B_NAME+NAM$B_TYPE for the total length. 


6.3 

NAM$B_BID 

The block identifier (BID) field is a static field that identifies this control block 
as a NAM block. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
NAM$C_BID (this is done by the VAX MACRO $NAM macro). 

6.4 

NAM$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
NAM block, in bytes. Once set, this field must not be altered unless the 
control block is no longer needed. This field must be initialized to the 
symbolic value NAM$C_BLN (this is done by the VAX MACRO $NAM 
macro). 

6.5 

NAM$B_DEV and NAM$I_DEV 

The device name length and address (DEV) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 

6.6 

NAM$W_DID 

The directory identification (DID) field identifies the directory for the file. 

VAX RMS outputs this 3-word field as part of the Open, Create, Display, and 
Parse services. If, once you open the file, you want to refer to this directory 
again, you can do so more quickly by specifying that the NAM block has a 
valid directory identifier. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 

6.7 

NAM$B_DIR and NAM$I_DIR 


The directory name length and address (DIR) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 
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6.8 

NAM$T_DVI 

The device identification (DVI) field defines the device for the file. VAX RMS 
outputs this field as part of the Open, Create, Display, and Parse services. 

You can use this field with the file identification field to reopen the file by 
referring to the NAM block. The symbolic value NAM$S_DVI gives the 
length of this field in bytes. The form of this field is a counted string. The 
first byte is a count of the number of characters following it. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 

6.9 

NAM$I_ESA 

The expanded string area address (ESA) field contains a symbolic address 
of a user buffer in the user program to receive the file specification string 
resulting from the translation of logical names and the application of default 
file specification information. 

You must specify this field for processing wildcard characters. 

6.10 

NAM$B_ESL 

The expanded string length (ESL) field is set by VAX RMS as part of the 
Open, Create, and Parse services. This field contains the length, in bytes, 
of the file specification string returned in the buffer whose address is in the 
NAM$L_ESA field. 

6.11 

NAM$B_ESS 

The expanded string area size (ESS) field contains the size of the user- 
allocated buffer whose address is contained in the NAM$L_ESA field. 

This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the file specification string, in the range of 0 through 
255. 

The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of an expanded file specification string. 

6.12 

NAM$W_FID 



The file identification (FID) field is a 3-word field set by VAX RMS to provide 
the identifier of the file on an Open, Create, or Display service. You can also 
set this field before opening the file if you are going to open by file identifier. 

This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 
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6.13 NAM$I_FNB 

The file name status bits (FNB) field is a binary options field set by VAX 
RMS to indicate status information about the file as determined by the file 
specification parsing routine. Each bit within this field denotes a specific 
status relative to the various components of the file specification. 

Each status bit has its own offset and mask value. For instance, the number 
of directory levels (DIR_LVLS) field has a symbolic bit offset of NAM$V_ 
DIR—LVLS and a mask value of NAM$M_DIR_LVLS. The bits, and the 
conditions they express for the NAM$L_FNB field are described in Table 6-2 
below. 


Table 6-2 NAM$L_FNB Status Bits 


Field Offset 

NAM$V_CNCI_DEV 

NAM$V_DIR_LVLS 

NAM$V_EXP_DEV 

NAM$V_EXP_DIR 

NAM$V_EXP_NAME 

NAM$V_EXP_TYPE 

NAM$V_EXP_VER 

NAM$V_GRP_MBR 


Description 

Device name is a concealed device. 

Number of subdirectory levels (value is 0 if there is a 
user file directory only), a 3-bit field. 

Device name is explicit. 

Directory specification is explicit. 

File name is explicit. 

File type is explicit. 

Version number is explicit. 

Directory specification is in the group/member number 
format. 


NAM$V_HIGHVER 

NAM$V_LOWVER 

NAM$V_NODE 

NAM$V_PPF 

NAM$V_QUOTED 


NAM$V_ROOT_DIR 
NAM$V_SE ARCH_LIST 

NAM$V_WILDCARD 

NAM$V_WILD_DIR 
NAM$V_WILD_GRP 
NAM$V_WILD_MBR 
NAM$V_WILD—NAME 


A higher-numbered version of the file exists (output 
from Create and Enter services). 

A lower-numbered version of the file exists (output 
from Create and Enter services). 

File specification includes a node name. 

File is indirectly accessed process permanent file. 

File specification includes a quoted string; indicates 
that the file name length and address field contains 
a quoted string file specification. Applies to network 
operations or magnetic tape devices only. 1 

Device name incorporates a root directory. 

A search list logical name is present in the file 
specification. 

File specification string includes a wildcard; returned 
whenever any of the other wildcard bits are set. 

Directory specification includes a wildcard character. 
Group number contains a wildcard character. 

Member number contains a wildcard character. 

File name contains a wildcard character. 
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Table 6-2 (Cont.) 

Field Offset 

NAM$V_WILD_SFD1 

to 

NAM$V_WILD_SFD7 

NAM$V_WILD_TYPE 

NAM$V_WILD_UFD 

NAM$V_WILD_VER 


NAM$I_FNB Status Bits 

Description 

Subdirectory 1 through 7 specification includes a 
wildcard character. 

File type contains a wildcard character. 

User file directory specification includes a wildcard 
character. 

Version number contains a wildcard character. 


6.14 NAM$B_NAME and NAM$I_NAME 

The file name length and address (NAME) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.15 NAM$B_NODE and NAM$L -NODE 

The node name length and address (NODE) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.16 NAM$B_NOP 


The name block options (NOP) field indicates the options applicable to the 
file name parsing services. 

The NAM$B_NOP field is a binary options field in which each option has a 
corresponding bit assignment. Multiple options can be specified (multiple bits 
can be set on). Options are identified by mnemonics. Each option has its own 
symbolic bit offset and mask value. For example, the SYNCHK option has 
a symbolic bit offset of NAM$V_SYNCHK and a mask value of NAM$M_ 
SYNCHK. 

Each of these options is discussed below. 

Options 

NAM$V_NOCONCEAL 

When used with the Open, Create, Search, or Display services, a concealed 
device logical name, if present, is translated into its physical device name (and 
directory, if so defined) in the resultant string field, whose address is supplied 
by the NAM$L_RSA field. If this option is not set and a concealed device 
name is used, the concealed device name appears in the resultant string field, 
instead of the physical device name (and directory, if so defined). By default, 
this bit is clear (not set). 
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NAM$V_PWD 

When used with the Create, Open, Parse, Search, or Display services, the 
password in the access control string of a node specification, if present, is 
returned unaltered in the expanded or resultant file specification fields. If this 
bit is not set, the actual password used is replaced by the word "password" in 
the resultant or expanded file specification string fields for security reasons. 

By default, this bit is clear (not set). 

NAM$V_SRCHXABS 

When used with the Search service for remote file access, this option directs 
VAX RMS to fill in the FAB and any chained XABs as if a Display service had 
been invoked. This allows you to obtain file attribute information using the 
Search service without the need to open the file. 

By default, this bit is cleared (not set). 

NAM$V_SYNCHK 

When used with the Parse service, the file specification is checked for syntax 
validity only without any I/O processing to ensure that the device, directory, 
and file actually exist. If this bit is not set, I/O processing occurs to ensure 
that the device, directory, and file do indeed exist. By default, this bit is 
clear (not set). If this bit is set, no device characteristics (FAB$L_DEV and 
FAB$L_SDC fields) are returned and the NAM$W_DID and NAM$T_DVI 
fields are not filled in. If this bit is set, the results of the SPARSE are not 
usable by subsequent Search services. 

6.17 NAM$I_RLF 

The related file NAM block address (RLF) field contains the symbolic address 
of the NAM block for the related file. This field supports the secondary file 
concept of the command language (DCL), giving an extra default level in 
processing file specifications. 

To provide an extra level of file specification defaults, the related NAM block 
must have been used previously by an Open, Create, Search or Display 
service to create a resultant file specification string. Moving the address of 
the related NAM block into the NAM$L_RLF field of the current NAM block 
specifies that the previously parsed NAM block's resultant file specification 
string should be used as a default when the current NAM block is parsed. 
Note that the previously parsed NAM block must contain a resultant file 
specification (see NAM$L_RSA and NAM$B_RSS for additional details.) 

Refer to the Guide to VAX/VMS File Applications for additional details on file 
specification parsing concepts. 

6.18 NAM$L_RSA 

The resultant string area address (RSA) field contains the symbolic address 
of a buffer in your program to receive the resultant file specification string. 
The NAM$B_RSS field must also be specified to obtain a resultant file 
specification string. 

This string is the fully specified name of the file that results from the 
resolution of all system defaults, including version numbers and wildcard 
character substitution in the expanded file name string. You must specify this 
field for wildcard processing. 
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6.19 


NAM$B_RSL 

The resultant string length (RSL) field is set by VAX RMS during Open, 
Create, Search, and Display services. This field contains the length, in bytes, 
of the resultant file specification string returned in the buffer whose address is 
in the NAM$L_RSA field. 


6.20 NAM$B_RSS 


The resultant string area size (RSS) field defines the size of the user-allocated 
buffer whose address is contained in the NAM$L_RSA field. 


This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the resultant file specification string in the range of 0 
through 255. 


The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of a resultant file specification string. 


6.21 



NAM$B_TYPE and NAM$I_TYPE 

The file type length and address (TYPE) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can tell 
which name string is used by referring to the NAM$B_ESL or NAM$B_RSL 
fields, which contain the length of the returned file specification string. 


6.22 



NAM$B_VER and NAM$I_VER 

The file version length and address (VER) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can 
determine the name string that is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


6.23 



NAM$L _WCC 

The wildcard context (WCC) field contains information required for using 
wildcard characters in place of the various file specification components. In 
particular, this field restarts a directory search to find the next matching file 
name, type, and/or version number. You may also use it to identify various 
VAX RMS extended contexts, for instance, during remote file processing. 
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7 Record Access Block (RAB) 


The record access block (RAB) defines run-time options for a record stream 
and for individual operations within a predefined record stream context. After 
you connect the file to a record stream and associate the record stream with 
a FAB, you use the RAB fields to specify the next record you want to access 
and to identify appropriate record characteristics. 


Summary of Fields 

The symbolic offset value, size, FDL equivalent, and a brief description of 
each RAB field are presented in Table 7-1. 

Table 7-1 RAB Fields 

Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

RABSB-BID 1 

1 

None 

Block identifier 

RAB$I_BKT 

4 

CONNECT BUCKET_CODE 

Bucket code 

RABSB—BLN 1 

1 

None 

Block length 

RAB$L_CTX 

4 

CONNECT CONTEXT 

User context 

RAB$L_FAB 

4 

None 

File access block address 

RAB$W_ISI 2 

2 

None 

Internal stream identifier 

RAB$L_KBF 

4 

None 

Key buffer address 

RAB$B_KRF 

1 

CONNECT KEY_OF_REFERENCE 

Key of reference 

RAB$B_KSZ 

1 

None 

Key size 

RAB$B_MBC 

1 

CONNECT MULTIBLOCK_COUNT 

Multiblock count 

RAB$B_MBF 

1 

CONNECT MULTIBUFFER—COUNT 

Multibuffer count 

RAB$L_PBF 

4 

None 

Prompt buffer address 

RAB$B_PSZ 

1 

None 

Prompt buffer size 

RAB$B_RAC 

1 

CONNECT 3 

Record access mode 

RAB$L_RBF 

4 

None 

Record buffer address 

RAB$W_RFA 

6 

None 

Record's file address 

RAB$L_RHB 

4 

None 

Record header buffer 

RAB$I_ROP 

4 

CONNECT 3 

Record-processing options 

RAB$W_RSZ 

2 

None 

Record size 

RAB$I_STS 2 

4 

None 

Completion status code 


Statically initialized field (by the VAX MACRO $RAB macro) to identify this control block as a RAB. 
2 Field cannot be initialized by VAX MACRO $RAB macro. 

3 Field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 7-1 (Cont.) RAB Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

RAB$L_STV 2 

4 

None 

Status value 

RAB$W_STV0 4 

2 

None 

Low-order word status value 

RAB$W_STV2 4 

2 

None 

High-order word status value 

RAB$B_TMO 

1 

CONNECT TIMEOUT_PERIOD 

Timeout period 

RAB$L_UBF 

4 

None 

User record area address 

RAB$W_USZ 

2 

None 

User record area size 

RAB$L_XAB 

4 

None 

Next XAB address 


2 Field cannot be initialized by VAX MACRO $RAB macro. 
4 Alternate definition of RAB$L_STV field. 


Each RAB field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $RAB and $RAB_STORE 
macros are described in Appendix B. 


7.2 RAB$B_BID 


The block identifier (BID) field is a static field that identifies the block as a 
RAB. Once set, this field must not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic offset value (this 
is done by the VAX MACRO $RAB macro). 


7.3 RAB$I_BKT 


The bucket code (BKT) field is used with records in a relative file and when 
performing block I/O. This field corresponds to the FDL attribute CONNECT 
BUCKET_CODE. 

This field contains a relative record number or a numeric value representing 
the virtual block number to be accessed. 

For relative files, the relative record number of the record acted upon (or 
which produced an error) is returned to the RAB$L_BKT field only after the 
completion of a sequential operation. That is, VAX RMS returns the relative 
record number when you set the record access mode for sequential access 
(RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service. 

Before performing block I/O on disk devices, you must store in this field 
the virtual block number (VBN) of the first block you want to read or write. 
For all other devices, this field is not used. If you specify a VBN of 0, VAX 
RMS will begin the block transfer at the block pointed to by the next block 
pointer (NBP). (The NBP is an internal pointer maintained by VAX RMS; it is 
described in Section 4.8.2.) 
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This field is also input to the Space service to specify the number of blocks to 
be spaced forward or backward. 


7.4 

RAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
RAB, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
RAB$C_BLN (this is done by the VAX MACRO $RAB macro). 

7.5 

RAB$I_CTX 

The user context (CTX) field contains any user-selected value, up to four bytes 
long. This field is devoted exclusively to your use. VAX RMS makes no use 
of the contents of this field; therefore, you can set any value you want in this 
field. For example, you could use this field to communicate with a completion 
routine in your program. 

This field corresponds to the FDL attribute CONNECT CONTEXT. 

7.6 

RAB$I_FAB 

The file access block address (FAB) field contains the symbolic address of the 
FAB for the file. Before you issue a Connect service, you must set this field to 
indicate the address of the FAB associated with the open file. 

7.7 

RAB$W_ISI 

The internal stream identifier (ISI) field associates the RAB with a 
corresponding FAB. VAX RMS sets this field after the execution of a Connect 
service. A Disconnect service clears this field. This field should not be altered. 

7.8 

RAB$I_KBF 



The key buffer address (KBF) field contains the symbolic address of the buffer 
containing the key for random access. Note that the RAB$B_KBF field has the 
same offset as the RAB$B_PBF (prompt buffer address) field, but no conflict 
is presented because the fields are used in mutually exclusive operations. 

You use this field when the RAB$B_RAC (record access mode) field specifies 
random access by key value and you set it to the address of the buffer that 
contains the key of the desired record. For a relative file (or for a sequential 
disk file with fixed-length records), the key is the relative record number. 

For an indexed file, the key is the key value within the record for the key of 
reference (RAB$B_KRF field). 

Before you issue a Get or Find service in random mode to an indexed file, you 
place the address of a location containing a key value in the RAB$L_KBF. 
The size of this key value must be specified in the RAB$B_KSZ field. During 
execution of the Get or Find service, VAX RMS uses the key value described 
by the RAB$L_KBF and RAB$B_KSZ fields to search an index (which you 
specify through the contents of the RAB$B__KRF field) and locate the desired 
record in the file. The type of match (that is, exact, generic, approximate, or 
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approximate and generic) that VAX RMS attempts between the key value you 
specify and key values in records of the file is determined by the RAB$B_KSZ 
field and the RAB$L_ROP field. 


7.9 RAB$B_KRF 


The key of reference (KRF) field specifies the key or index (primary, first 
alternate, and so on) to which the operation applies. The RAB$B_KRF field 
is applicable to indexed files only. This field corresponds to the FDL attribute 
CONNECT KEY_OF_REFERENCE. 

This field contains a numeric value representing the key path to records in a 
file. The value 0, the default, indicates the primary key. The values 1 through 
254 indicate alternate keys. 

When your program issues a Get or Find service in random access mode, the 
key of reference specifies the index to search for a match on the key value 
that is described by the RAB$L_KBF and RAB$B_KSZ fields. When your 
program issues a Connect or Rewind service, the key of reference identifies 
the index in the file of the next record in the stream. The next record is 
important when records are retrieved sequentially. 


7.10 RAB$B_KSZ 


The key size (KSZ) field contains a numeric value equal to the size, in bytes, 
of the record key pointed to by the RAB$L_KBF field. 

Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ 
(prompt buffer size) field but no conflict is presented because the fields are 
used in mutually exclusive operations. 

For indexed files, the size of the key depends on the key data type: 

• For string keys, a value from 1 through the size of the key field can be 
used. If the specified size is less than the size of the key field, then only 
the leftmost characters of each key are used for comparison. 

• For numeric key data types, a value of 0 causes VAX RMS to use the key 
data type defined at file creation to determine the key size. A nonzero 
value is checked against the defined size, and an error is returned if they 
are not equal. 

Note that for DECnet operations, the RAB$B__KSZ field must be explicitly 
specified as a nonzero value because the key data type information may not 
be available to VAX RMS at the local node. 

The size of the relative record number of a record in a relative file or a 
sequential file with fixed length records is a longword, positive, integer value; 
therefore, the key size is 4. For relative record numbers, the default value 
of 0 causes a key size of 4 to be used. For DECnet operations, however, the 
RAB$B_KSZ field must be explicitly specified as 4 for relative files. 

With indexed files, the size of key values in bytes of an indexed file can be 
from 1 to 255 bytes. 

A program may access indexed file records direcly in one of four ways: 

• By an exact match 

• By an approximate match 
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• By a generic match 

• By a combination of the approximate and generic matches 

The program specifies the type of match using the RAB$B_KSZ field 
together with 2 bits from the RAB$L_ROP field, the RAB$V_KGE (logically 
synonymous with RAB$V_JEQNXT) bit and the RAB$V_KGT (logically 
synonymous with RAB$V_NXT) bit. 

• To specify an exact match, set a value in the RAB$B_KSZ field equal 
to the number of bytes in the key, and set the RAB$V_KGE bit and the 
RAB$V_KGT bit to off. 

• To specify an approximate match, set a value in the RAB$B_KSZ field 
equal to the number of bytes in the key, and set the appropriate bit to 
on. Specifically, if you want to match on a record having either an equal 
key value, or the next value (greater for ascending sort order, lesser for 
descending sort order) set the RAB$V_KGE (logically synonymous with 
RAB$V__EQNXT) bit to on. If you want to match on a record having the 
next value and to ignore equal key values, set the RAB$V_KGT (logically 
synonymous with RAB$V_NXT) bit to on. 

Note: Sort order is established in the data type (XAB$B__DTP) field of the 
associated XABKEY when the file is created. 

• To specify a generic match, set a value in the RAB$B_JCSZ field equal to 
the number of leading bytes in the key you want to match on, and set 
both bits to off. 

• To specify an approximate generic match, set a value in the RAB$B__KSZ 
field equal to the number of leading bytes in the key you want to match 
on, and set the appropriate bit to on. 


7.11 RAB$B_MBC 

The multiblock count (MBC) field applies only when accessing a sequential 
disk file. This field specifies the number of blocks, in the range of 0 through 
127, to be allocated to each I/O buffer and correspondingly, the number of 
blocks of data to be transferred in each I/O unit . If this field is not specified 
or is specified as 0, the process default for the multiblock count is used. If 
the process default is also 0, VAX RMS uses the system default. If the system 
default is also 0, then the default size for each I/O buffer is 1 block. The DCL 
command SET RMS_DEFAULT is used to set process or system defaults. This 
field corresponds to the FDL attribute CONNECT MULTIBLOCK_COUNT. 

VAX RMS examines the RAB$B_MBC during the execution of a Connect 
service to determine the number of blocks in the I/O transfers for this record 
stream and allocates a buffer with the appropriate storage capacity. Note that 
the RAB$B_MBF (multibuffer count) field may be used to allocate multiple 
buffers of this size for the record stream. 

The use of the RAB$B__MBC field optimizes data throughput for sequential 
operations, and in no way affects the structure of the file. It reduces the 
number of times you would have to access the disk for record operations, 
which can thereby accelerate the speed of execution. However, the extra 
buffering increases memory requirements. 
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Note that the RAB$B__MBC field is not used with block I/O. With 
multiblocks, the number of blocks in an I/O unit is fixed by the multiblock 
count attribute, whereas in block I/O operations the number of blocks being 
transferred is specified by the program. 

This field is not supported for DECnet operations; it is ignored. 

7.12 RAB$B_MBF 

The multibuffer count (MBF) field indicates the number of process-local I/O 
buffers you want VAX RMS to allocate when you issue a Connect service 
for a record stream. This field corresponds to the FDL attribute CONNECT 
MULTIBUFFER_COUNT. 

This field contains a numeric value in the range of 0 to 127 that represents 
the number of buffers to be allocated. 

If this field is not specified or is set to 0, VAX RMS uses the process default 
for the particular file organization and device type. If the process default is 
also 0, the system default for the particular file organization and device type 
applies. If the system default is likewise 0, one buffer is allocated. However, 
if read-ahead or write-behind is specified, a minimum of two buffers will be 
allocated. A minimum of two buffers will also be allocated for an indexed 
file. 

VAX RMS requires that at least one buffer be allocated for sequential and 
relative files and at least two buffers be allocated for indexed files, unless the 
file is to be processed with block I/O operations only. Multiple buffers can 
be used efficiently to overlap I/O time with compute time, particularly in 
read-ahead or write-behind processing (see RAB$L_ROP for information on 
these options), and to increase use of the buffers (as compared to disk I/O) 
when performing random processing. 

Note that the RAB$B_MBF field is not used when block I/O access is 
specified with the Open, Create, or Connect services because no buffers 
are required. 

This field is not supported for DECnet operations; it is ignored. 

7.13 RAB$I_PBF 

The prompt buffer address (PBF) field points to a character string to be used 
as a prompt for terminal input. Note that the RAB$B_PBF field has the same 
offset as the RAB$B_KBF (key buffer address) field but because the fields are 
used in mutually exclusive operations, no conflict is presented. 

This field contains the symbolic address of the buffer containing the prompt 
character string. If you select the RAB$V_PMT option of the RAB$L_ROP 
field when you issue a Get service, this character string is output to the 
terminal before the Get service is performed. 

To perform any carriage control on the terminal, you must insert the 
appropriate carriage control characters into this character string. 

This field is not supported for DECnet operations; it is ignored. 
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7.14 RAB$B_PSZ 

The prompt buffer size (PSZ) field indicates the size of the prompt character 
string to be used as a terminal prompt. This field contains the size, in bytes, 
in the range of 0 to 255. 

Note that the RAB$B_PSZ field has the same offset as the RAB$B_KSZ (key 
buffer size) field but no conflict is presented because the fields are used in 
mutually exclusive operations. 

This field is not supported for DECnet operations; it is ignored. 


7.15 RAB$B_RAC 

The record access mode (RAC) field indicates the method of retrieving or 
inserting records in the file, that is, whether records will be read (or written) 
sequentially, directly or by record file address. Only one access method may 
be specified for any single record operation, but you can change the record 
access mode between record operations. 

The RAB$B_RAC field is not applicable to block I/O operations and there is 
no corresponding FDL attribute for this field. 

The RAB$B_RAC field is a keyword value field in which each record access 
mode has a symbolic offset value. Options are identified using mnemonics. 
Each access mode in the RAB$B_RAC field has its own symbolic constant 
value. For example, the SEQ (sequential) access mode has a symbolic constant 
value of RAB$C_SEQ. 

The record access mode options and their meanings are described below. 

Options 
RAB$C_SEQ 

Indicates sequential record access mode (the default); it can be specified with 
any type of file organization. 

Records read from (or written to) sequential or relative files are accessed in 
chronological order. That is, older records are accessed before newer records. 

Records read sequentially from indexed files are accessed by the key of 
reference according to the key's sort order. Where records have duplicate 
keys, older records are read before newer records regardless of the key's sort 
order. 

For example, assume an ascending key indexed file with four 2-byte records 
(Al, Bl, B2, Cl) where the key is the first byte of each record. When 
processed sequentially, the records would be encountered in the following 
order: 


Al Bl B2 Cl 

Here records Bl and B2 have the duplicate key B, but record Bl was inserted 
chronologically before record B2 and therefore, is encountered before B2 
when reading records sequentially. 
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If this file is reorganized as a descending-key indexed file, the records are 
encountered in the following order: 

Cl B1 B2 A1 

Note that the chronological order of insertion for the two records with 
duplicate keys is maintained without regard to sort order. 

When records are written sequentially to indexed files, VAX RMS verifies that 
the key value of each successive record is ordered correctly with respect to the 
key value in the previously written record. For example, with a descending 
key of reference VAX RMS ensures that the key value of the third record 
written is less than the value of the second record. 

RAB$C_KEY 

Indicates random access by key. For relative files and sequential files on 
disk with fixed-length records, random access is by relative record number. 
Indexed files are accessed directly by specifying the appropriate value for the 
key of reference. 

RAB$C_RFA 

Indicates random access by record's file address; used for all disk file 
organizations. 

7.16 RAB$I_RBF 

The output record buffer address (RBF) field contains the symbolic address 
of the buffer that holds the record to be written. When you issue a Put or 
Write service, this field must specify the address of the record to be written 
to the file. When you issue an Update service, this field is required if the file 
contains variable-length or VFC records. 

When you issue a Get or Read service, VAX RMS sets this field to the address 
of the record just read from the file; you need not initialize this field. 

7.17 RAB$W_RFA 

The record file address (RFA) field comprises 3 words that define the physical 
disk address (not symbolic address) of the current record. 

After the successful execution of a Get, Put, or Find service, VAX RMS sets 
the RAB$W_RFA field to the address of the record acted on by the operation. 
This address provides an unambiguous means of directly locating this same 
record at some later time but is meaningful for disk files only. 

You can store the contents of the RAB$W__RFA field for future use. When 
you want to retrieve the record again, merely restore the saved contents of 
the field, set the record access mode to random by RFA, and issue a Get or 
Find service. 

The following rules apply to RFA access: 

1 There are two additional names for portions of this field: RAB$L_RFA0 is 
the offset of the first of three words; RAB$W_RFA4 is the offset of the last 
word. 
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Using VAX MACRO, the field may be copied: 

MOVAL RABBLK.RO 

MOVL RAB$L_RFA0(R0).SAVE.RFA 

MOVW RAB$W_RFA4(RO).SAVE.RFA+4 

2 RFA values remain valid for a record in a sequential file as long as the 
record is within the space defined by the logical file; that is, until the file 
is truncated to a point before the record. 

3 RFA values remain valid for a record in a relative file for the life of the 
file; that is, until the file is deleted or reorganized using the VAX/VMS 
Convert Utility. 

4 With an indexed file, RFA values remain valid until the file is reorganized 
using the VAX/VMS Convert Utility or deleted. Note that the VAX/VMS 
Convert/Reclaim Utility partially reorganizes a file while maintaining RFA 
values. 


7.18 RAB$I_RHB 

The fixed-length record header buffer (RHB) field contains the symbolic 
address of the record header buffer, which is used only when processing VFC 
records. 

For a Get service, VAX RMS strips the fixed control area portion of the record 
and places it in the buffer whose address is specified in this field. For Put or 
Update services, VAX RMS writes the contents of the specified buffer to the 
file as the fixed control area portion of the record. 

If this field is not specified, an address of 0 is assumed, which indicates the 
absence of a buffer; the fixed control area is discarded for a Get service, 
zeroed for a Put service, and left unchanged for an Update service. 

The size of the fixed control area is defined in the FAB, using the FAB$B__FSZ 
field. You must ensure that the buffer size described in the RAB$L__RHB field 
is equal to the value specified by the FAB$B_FSZ field. 


7.19 RAB$L_ROP 

RAB$L_ROP is the symbolic offset value for the RAB's record-processing 
options (ROP) field. This field specifies which of the various optional record 
operations are to be implemented for the program and corresponds to the 
FDL primary attribute CONNECT. 

The ROP is a 32-bit field in which each record-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple bits 
can be set), when applicable. Each option has a unique symbolic offset value 
and mask value but you need only specify the appropriate 3-letter mnemonic 
when coding a function. For example, the end-of-file option has a symbolic 
offset value of RAB$V_EOF but to specify the option, you use the following 
MACRO statement: 

R0P=E0F 

The record-processing option bits are never affected by VAX RMS services. 
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This section describes the record-processing options alphabetically by 
functional category of which there are seven: 

• Connect service input options 

• Indexed file options 

• Miscellaneous options 

• Performance options 

• Put service options 

• Record locking options 

• Terminal device options 

Table 7-2 lists each of the options alphabetically by category. 

Table 7-2 File Processing Options 

Option Symbolic Offset 

Connect service options 

Asynchronous RAB$V_ASY 


Block I/O 
End of file 
Read ahead 
Write behind 


RAB$V_BIO 

RAB$V_EOF 

RAB$V_RAH 

RAB$V_WBH 


Indexed file options 


Key greater than or equal 

Limit 

Load 

Key greater than 


RAB$V_EQNXT (or RAB$V_KGE) 

RAB$V_LIM 

RAB$V_LOA 

RAB$V_NXT or (RAB$V_KGT) 


Miscellaneous options 
Timeout 

Performance options 


RAB$V_TMO 


Asynchronous 
Fast delete 
Locate mode 
Read ahead 
Write behind 


RAB$V_ASY 

RAB$V_FDL 

RAB$V_LOC 

RAB$V_RAH 

RAB$V_WBH 


Put service options 


Truncate on put 
Update-if 


RAB$V_TPT 

RAB$V_UIF 


Record locking options 


Do not lock 
Nonexistent record 
Lock for read 
Lock for write 


RAB$V_NLK 

RAB$V_NXR 

RAB$V_REA 

RAB$V_RLK 
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Table 7-2 (Cont.) File Processing Options 


Option 


Symbolic Offset 


Ignore read lock 
Timeout 
Manual unlock 
Wait to lock 


RAB$V_RRL 

RAB$V_TMO 

RAB$V_ULK 

RAB$V_WAT 


Terminal device options 


Cancel CTRL/O 
Convert 

Extended operation 
Prompt 

Purge type-ahead 
Read, no echo 
Read, no filter 
Timeout 


RAB$V_CCO 

RAB$V_CVT 

RAB$V_ETO 

RAB$V_PMT 

RAB$V_PTA 

RAB$V_RNE 

RAB$V_RNF 

RAB$V_TMO 


In the following text, each of the options is described under its symbolic 
offset value. For example, the asynchronous option is described under 

RAB$V_ASY. 

Connect Service Options 
RAB$V_ASY 

Asynchronous; see explanation under "Perfomance Options" later in this 
section. Note that I/O may take place during the Connect service for indexed 
files and for network operations. 

RAB$V_BIO 

Block I/O; specifies that only block I/O operations are to occur, when mixed 
record I/O and block I/O operations are allowed. This option is meaningful 
only if the FAB$B_FAC FAB$V_BRO option was specified when the file was 
opened (by a Create or Open service). When the RAB$V_BIO option is set 
for the Connect service, only block I/O operations are allowed for this record 
stream. When the RAB$V_BIO option is clear for the Connect service, only 
record I/O operations are allowed when accessing a relative or indexed file 
and mixed (block I/O and record I/O) operations are allowed for sequential 
files. This option corresponds to the FDL attribute CONNECT BLOCK_IO. 

RAB$V_EOF 

End-of-file; indicates that VAX RMS is to position the record stream to the end 
of the file for the connect record operation only, unless used with a shared 
sequential file. When used with a shared sequential file, this indicates that 
the user wishes to append data to the end of the file and therefore VAX RMS 
positions the record stream to the end of the file for every record operation. 
This option corresponds to the FDL attribute CONNECT END_OF_FILE. 

RAB$V_RAH, RAB$V_WBH 

Read ahead and write behind; (see explanation under "Options Affecting 
Record Operation Performance" later in this section)). 
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Indexed File Options 

Note that the first three indexed file options have limited application with 
relative files. See the Guide to VAX/VMS File Applications for details. 

The indexed file options may be be enabled or disabled during any record 
operation. 

As shown in the following chart, synonyms have been defined for the two key 
search options, RAB$V__KGT and the RAB$V_KGE, to reflect the functional 
capability for processing records in ascending and descending order. DIGITAL 
recommends you use these synonyms when coding new applications. 


Search Option 

Synonym 

Definition 

RAB$V_KGE 

RAB$V_EQNXT 

Return the record with an equal key 
value, or the next key value according 
to the sort order for the current key of 
reference. 

RAB$V_KGT 

RAB$V_NXT 

Return the record with the next key 
value according to the sort order for the 
current key of reference. 


RAB$V_EQNXT 

This option corresponds to the FDL CONNECT attribute KEY_GREATER_ 
EQUAL, and the bit's symbolic offset value, RAB$V__EQNXT, is logically 
synonymous with the symbolic offset value RAB$V__KGE. When the bit is set 
and ascending sort order is specified, VAX RMS returns the next record having 
a key value equal to or greater than the value specified by the RAB$L_KBF 
and RAB$B_KSZ fields. If descending sort order is specified, VAX RMS 
returns the next record that contains a key value equal to or less than the 
value specified by the RAB$L__KBF and RAB$B_KSZ fields. 

Note: Sort order is established in the data type field (symbolic offset XAB$B__ 
DTP) of the associated XABKEY when the file is created. 

If the program specifies a RAB$V_EQNXT search and no record has a key 
value identical to the specified search value, VAX RMS returns the record with 
the next key value according to the specified sort order. (See the description 
of the RAB$V_NXT bit.) 

If the program specifies a RAB$V_EQNXT search and a record with a key 
value identical to the search key is found, VAX RMS returns the record 
regardless of sort order. 

For example, consider an ascending-key indexed file having three records. A, 
B, and C, where the key for each record is the record itself. When the file is 
processed sequentially, the records are encountered in the following order: 

ABC 

If the program does a RAB$V__EQNXT search specifying the B key value, 
VAX RMS returns record B. 


7-12 








Record Access Block (RAB) 

RAB$I_ROP 


If this file is reorganized as descending-key indexed file and it is processed 
sequentially, the records are encountered in the following order: 

c B A 

Again, when the program does a RAB$V_EQNXT search specifying the B key 
value, VAX RMS returns record B. 

If neither a RAB$V_EQNXT search nor RAB$V_NXT search (logically 
synonymous with RAB$V_KGT) is specified, an exact key match is required 
unless a generic key match is specified. (See the description of the RAB$B_ 
KSZ bit.) 

RAB$V_KGE 

This option is logically synonymous with the RAB$V__EQNXT option and is 
described under RAB$VJEQNXT. 

RAB$V_KGT 

This bit is logically synonymous with, and is described under, RAB$V__NXT. 

RAB$V_LIM 

This attribute permits you to use VAX RMS as a limit sensor when accessing 
a file sequentially. When the RAB$V_LIM bit is set, the key value defined 
by the RAB$L_KBF and RAB$B_KSZ fields (limit key value) is compared 
to the key value in each record as it is accessed. When a record is accessed 
that has a key value different from the limit key value, VAX RMS returns the 
RMS$_OK_LIM success status code. 

This option corresponds to the FDL attribute CONNECT KEY-LIMIT. 

RAB$V—LOA 

Load; specifies that VAX RMS is to load buckets according to the fill size 
established when the file is created. The bucket fill size is established defined 
in the XAB$W_DFL and XAB$W_IFL fields of the key definition XAB. If 
LOA is not specified, VAX RMS ignores the established bucket fill size; that 
is, buckets will be completely filled. This option corresponds to the FDL 
attribute CONNECT FILL-BUCKETS. 

RAB$V_NXT 

This option corresponds to the FDL CONNECT attribute KEY—GREATER— 
THAN, and the bit's symbolic offset value (RAB$V_NXT) is logically 
synonymous with the symbolic offset value RAB$V_KGT. When the bit is 
set and ascending sort order is specified, VAX RMS returns the next record 
having a key value greater than the value specified by the RAB$L_KBF and 
RAB$B_KSZ fields. If descending sort order is specified, VAX RMS returns 
the next record having a key value less than the value specified by the 
RAB$L_KBF and RAB$B_KSZ fields. If neither RAB$V_KGT nor RAB$V— 
EQNXT (logically synonymous with RAB$V—KGE) is specified, an exact key 
match is required. 

Note: Sort order is established in the data type XAB$B_DTP field of the 
associated XABKEY when the file is created. 

The key searching will usually produce different results depending on the 
specified sort order. For example, consider an ascending-key indexed file 
having three records. A, B, and C, where the key for each record is the record 
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itself. When the file is processed sequentially, VAX RMS returns the records 
in the following order: 

ABC 

If the program does a RAB$V_KGT search specifying the B key value, VAX 
RMS returns record C. 

If this file is reorganized as descending-key indexed file and is processed 
sequentially, the records are returned in the following order: 

c B A 

Now when the program does a RAB$V_KGT search specifying the B key 
value, VAX RMS returns record A. 

Miscellaneous Options 
RAB$V_TMO 

Timeout; in addition to its use for terminals and preventing delays due 
to record locks (described later), the RAB$V_TMO option serves a special 
purpose for mailbox devices. If specified in combination with a timeout 
value of 0 (RAB$B_TMO field). Get and Put services to mailbox devices 
will use the IO$M_NOW modifier. Doing so will cause the operation to 
complete immediately, instead of synchronizing with another cooperating 
writer or reader of the mailbox. This option corresponds to the FDL attribute 
CONNECT TIMEOUT__ENABLE and is not supported for DECnet operations. 
See the VAX/VMS I/O Reference Volume for a further discussion of mailboxes. 

Performance Options 
RAB$V_ASY 

Asynchronous; indicates that this I/O operation is to be performed 
asynchronously. When you specify RAB$V__ASY, VAX RMS will return 
control to your program as soon as an I/O operation is initiated, even though 
that operation may not yet be completed. This option is normally used 
with a Wait service to synchronize with operation completion; it is ignored 
for process permanent files. This option corresponds to the FDL attribute 
CONNECT ASYNCHRONOUS. 

RAB$V_FDL 

Fast delete; applies only to Delete services on indexed files. When specified, 
the pointers from alternative indexes that allow duplicates are not removed 
immediately; they are deleted when the deleted record is subsequently 
accessed using the alternate key, when an error message is returned. This 
option saves an index search on those indexes when deleting records, but it 
later requires an index search when following the pointers (that this option 
avoids deleting) to a nonexistent record. This option corresponds to the FDL 
attribute CONNECT FAST_DELETE. 

RAB$V_LOC 

Locate mode; under specified conditions, record operations involving the Get 
service will use locate mode, not move mode. For specified record retrieval 
operations, you have the option of specifying locate mode instead of move 
mode, the default method of buffer handling. In locate mode, your program 
accesses records directly in an I/O buffer. Thus, VAX RMS does not have to 
move records between I/O buffers and a user program buffer. The RAB$L_ 
ROP RAB$V_LOC option, when set, activates locate mode. This option must 
be selected for use only with the Get service and is not supported for use 
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with the Put or Update services. Here is a list of conditions that may prohibit 
the use of the locate mode option: 

• Record cross block boundaries 

• The FAB$B_FAC field FAB$V_UPD option is set 

• There are multiple record streams 

• Process permanent files are accessed indirectly 

• Records are compressed in indexed Prolog 3 files 

In move mode, VAX RMS transfers individual records between I/O buffers 
and your program buffer. When you invoke a Get service, VAX RMS reads 
a block or set of blocks (for sequential files) or a bucket (for relative and 
indexed files) into an I/O buffer. VAX RMS then selects the desired record 
from the buffer and moves it into the program-specified location. Locate 
mode eliminates the last step. 

This option corresponds to the FDL attribute CONNECT LOCATE-MODE 
and it is not supported for DECnet operations; move mode is always used. 

RAB$V—RAH 

Read-ahead; used with multiple buffers (see RAB$B_MBF) to indicate read- 
ahead operations. VAX RMS issues I/O requests as soon as possible when 
a buffer will be needed shortly. When the first buffer is filled, the I/O 
operation takes place for the first buffer as the second buffer receives the next 
record; the second buffer soon becomes filled and the next record is read into 
the first buffer as the I/O operation for the second buffer occurs. The system 
does not have to wait for I/O completion, which permits an overlapping of 
input and computing. Read-ahead is ignored for unit record device I/O and 
is supported only for the sequential file organization when file sharing is not 
requested. If the RAB$V_RAH option is specified when the multibuffer count 
(RAB$B_MBF field) is 0, two buffers will be allocated to allow multibuffering. 
If two or more buffers are specified, multibuffering will be allowed regardless 
of what was specified to the Connect service. Conversely, if a buffer count of 
1 is specified, multibuffering is disabled regardless of what was specified to 
the Connect service. This option corresponds to the FDL attribute CONNECT 
READ__AHEAD and it is not supported for DECnet operations. 

RAB$V_WBH 

Write-behind; used with multiple buffers (see RAB$B_MBF). When one 
buffer is filled, the next record is written into the next buffer while the I/O 
operation takes place for the first buffer. The system does not have to wait for 
I/O completion, which allows for an overlapping of computing and output. 
Write-behind is ignored for unit record devices. This option is implemented 
only for the sequential file organization when file sharing is not requested. 

If the RAB$V_WBH option is specified when the multibuffer count (RAB$B_ 
MBF field) is 0, two buffers will be allocated to allow multibuffering. If two 
or more buffers are specified, multibuffering will be allowed regardless of 
what was specified to the Connect service. Conversely, if a buffer count of 
1 is specified, multibuffering is disabled regardless of what was specified to 
the Connect service. This option corresponds to the FDL attribute CONNECT 
WRITE-BEHIND and it is not supported for DECnet operations. 
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Put Service Options 
RAB$V_TPT 

Truncate-on-put; specifies that a Put or Write service using the sequential 
record access mode can occur at any point in the file, truncating the file at 
that point. The end of file mark is set to the position immediately following 
the last byte written. This option applies only to sequential files. The process 
must have specified truncate access by setting the FAB$V_TRN option in 
the FAB$B_FAC field when the file was opened or created. This option 
corresponds to the FDL attribute CONNECT TRUNCATE_ON_PUT. 

RAB$V_UIF 

Update-if; indicates that if a Put service is issued for a record that already 
exists in the file, the operation is converted to an Update. This option is 
necessary to overwrite (as opposed to update) an existing record in relative 
and indexed files. Indexed files using this option must not allow duplicates 
on the primary key. The process must have specified Update access by setting 
the FAB$V_UPD option in the FAB$B_FAC field when the file was opened or 
created. This option corresponds to the FDL attribute CONNECT UPDATE__ 
IF. When using this option with shared files and automatic record locking, 
you should be aware that the Put service, unlike the Update service, will 
briefly release record locks until it is determined that an Update should take 
place. At that point, the record is relocked for the Update operation. Note 
that during the time the Put operation is being converted into an Update 
operation, it is possible that another record stream could update or delete the 
record. 

Record locking options 

The record-processing options related to controlling record locking are 
described below. Except as noted, these options apply to to all file 
organizations and may be selected for each operation. 

RAB$V__NLK 

Do not lock record; specifies that the record accessed through a Get or 
Find service is not to be locked. The RAB$Y_JMLK option takes precedence 
over the RAB$Y_ULK option. This option corresponds to the FDL attribute 
CONNECT NOLOCK. 

RAB$V_NXR 

Nonexistent record processing; specifies that if the record directly accessed 
through a Get or Find service does not exist (was never inserted into the 
file or was deleted), the service is to be performed anyway. This option 
applies only to relative files. For a Get service, the previous contents of a 
deleted record are returned. The processing of a deleted record returns a 
completion status code of RMS$_OK_DEL, and the processing of a record 
that never existed returns RMS$_OK_RNF. This option corresponds to the 
FDL attribute CONNECT NONEXISTENT_RECORD. 

RAB$V_REA 

Lock record for read; specifies that the record is to be locked for a read 
operation for this process, while allowing other accessors to read the record 
(but not to modify the record). Use this option only when you do not want 
the file to be modified by any subsequent activities. Use the RAB$V__RLK 
option to allow possible subsequent modification of the file. This option 
corresponds to the FDL attribute CONNECT LOCK_ON_READ. 
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RAB$V_RLK 

Lock record for write; specifies that a user who locks a record for modification 
is allowing the locked record to be read by other accessors. If both RAB$V_ 
RLK and RAB$V_REA bits are specified, the RAB$V_REA bit is ignored. The 
RAB$V_NLK bit takes precedence over all others. This option corresponds to 
the FDL attribute CONNECT LOCK_ON —WRITE. 

RAB$V_RRL 

Read regardless of lock; read the record even if another stream has locked 
the record. This option allows the reader some control over access. If a 
record is locked against all access and this bit is set for either a Put or Get 
service request, the record will be returned with alternate status RMS$_ 
OK_RRL. This option corresponds to the FDL attribute CONNECT READ- 
REGARDLESS. 

RAB$V_TMO 

Timeout; specifies that if the RAB$V_WAT option was specified, the RAB$B_ 
TMO field contains the maximum time value, in seconds, to be allowed for 
a record input wait caused by a locked record. If the timeout period expires 
and the record is still locked, VAX RMS will abort the record operation with 
the RMS$_TMO completion status. Note that the maximum time allowed 
for a timeout is 255 seconds. Other functions of the RAB$V_TMO option are 
listed under "Miscellaneous Options." This option corresponds to the FDL 
attribute CONNECT TIMEOUT—ENABLE and it is not supported for DECnet 
operations. 

RAB$V_ULK 

Manual unlocking; specifies that VAX RMS will not automatically unlock 
records. Instead, once locked (through a Get, Find, or Put service), a record 
must be specifically unlocked by a Free or Release service. The RAB$V_NLK 
option (above) takes precedence over the RAB$V_ULK option. This option 
corresponds to the FDL attribute CONNECT MANUAL—UNLOCKING. 

RAB$V_WAT 

Wait; if the record is currently locked by another stream, wait until it is 
available. This option may be used with the RAB$V_TMO option (see above) 
to limit waiting periods to a specified time interval. This option corresponds 
to the FDL attribute CONNECT WAIT—FOR—RECORD. 

Terminal Device Options 

The record-processing options related to terminal devices are described 
below. These options map directly into equivalent modifiers to the QIO 
function code. For a further discussion of their effects, see the VAX/VMS I/O 
Reference Volume. These options can be selected for each operation. 

RAB$V_CCO 

Cancel CTRL/O; guarantees that terminal output will not be discarded if 
the operator presses CTRL/O. This option corresponds to the FDL attribute 
CONNECT TT_CANCEL—CONTROL—O and it is not supported for DECnet 
operations. 

RAB$V_CVT 

Convert; changes characters to uppercase on a read from a terminal. This 
option corresponds to the FDL attribute CONNECT TT_UPCASE —INPUT 
and it is not supported for DECnet operations. 
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RAB$V_ETO 

Extended terminal operation; indicates presence of a Terminal XAB (XABTRM) 
to describe terminal input using extended terminal characteristics. Note that 
if this option is specified, all other RAB$L_ROP options specific to terminal 
devices are ignored (including the RAB$V_TMO option). This option is not 
supported for DECnet operations. 

RAB$V_PMT 

Prompt option; indicates that the contents of the prompt buffer are to be 
used as a prompt for reading data from a terminal (see RAB$L_PBF). This 
option corresponds to the FDL attribute CONNECT TT_PROMPT and is not 
supported for DECnet operations. 

RAB$V_PTA 

Purge type-ahead; eliminates any information that may be in the type-ahead 
buffer on a read from a terminal. This option corresponds to the FDL attribute 
CONNECT TT_PURGE _TYPE —AHEAD and it is not supported for DECnet 
operations. 

RAB$V_RNE 

Read no echo; indicates that input data is not echoed (displayed) on the 
terminal as it is entered on the keyboard. This option corresponds to the 

FDL attribute CONNECT TT_READ_N0ECF10 and it is not supported for 
DECnet operations. 

RAB$V_RNF 

Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be 
considered control commands on terminal input but are to be passed to the 
user program. This option corresponds to the FDL attribute CONNECT TT_ 
READ—NOFILTER and it is not supported for DECnet operations. 

RAB$V_TMO 

Timeout; for terminal operations, indicates that the content of the RAB$B_ 
TMO field is to be used to determine the number of seconds allowed between 
characters received during terminal input. If the timeout period expires, 

VAX RMS returns an error status (see RAB$B_TMO). Other functions of the 
RAB$V_TMO option are listed under "Miscellaneous Options and Record 
Locking Options". This option corresponds to the FDL attribute CONNECT 
TIMEOUT_ENABLE and is not supported for DECnet operations. 

7.20 RAB$W_RSZ 

The record size (RSZ) field contains the size, in bytes, of the record. For a 
Write service, the range is 1 through 65,535. For a Put or Update service, the 
range is 0 to the maximum value shown in Table 5-4. This field controls the 
size of a record that a Put or Update service can write, or the number of bytes 
that a Write (block I/O) service can write. This field is required for an Update 
service only if the file contains variable-length or variable with fixed-control 
records. 

On input from a file, VAX RMS sets this field to indicate the length, in bytes, 
of the record that a Get service transfers or that a Read service (block I/O) 
reads. 
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Three notes apply to this field: 

1 After a Get service, VAX RMS places the size of the record retrieved into 
the RAB$W_RSZ field. On a Read service, VAX RMS sets the RAB$W__ 
RSZ field to the number of bytes actually transferred. 

2 For variable with fixed-length control records, VAX RMS does not include 
the size of the fixed control area in the RAB$W_RSZ field. 

3 For block I/O operations, some devices require that an even number of 
bytes be transferred. 


7.21 

RAB$I_STS 

The completion status code (STS) field is set by VAX RMS with the success 
or failure status codes for a record operation before returning control to your 
program. For an asynchronous operation that has been initiated but not yet 
completed, this field is 0. When the operation is complete, the field will be 
updated with the completion status. See Part I for additional details about 
signaling VAX RMS status codes. Potential error codes for specific operations 
are listed with their description in Part III. 

7.22 

RAB$I_STV 

The completion status value (STV) field communicates additional completion 
information to your program, on the basis of the type of operation and the 
contents of the completion status code field. For additional information on 
the RAB$L_STS and RAB$L_STV fields, see Part I. 



The RAB$L_STV field can be accessed using alternate symbolic offsets; 
RAB$W_STV0 is the location of the first word and RAB$W_STV2 is the 
location of the second word within RAB$L_STV. 

7.23 

RAB$B_TMO 



The timeout period (TMO) field indicates the maximum number of seconds, in 
the range 0 to 255, that VAX RMS should wait for an operation to complete. 
If the operation does not complete before the specified timeout period, VAX 
RMS returns an error status code. This field corresponds to the FDL attribute 
CONNECT TIMEOUT_PERIOD. 

To use this field, you must also specify the RAB$V_TMO record-processing 
option (RAB$L_ROP field). 

For a Get service using a terminal device, this value specifies the number 
of seconds to wait between the characters being typed. If you specify 0 
along with RAB$V_TMO, the current contents of the type-ahead buffer are 
returned. 

For a wait on record lock (RAB$L_JROP option RAB$V_WAT) with a Get, 
Find, or Put service, this value specifies the maximum number of seconds for 
VAX RMS to wait for the record to become available. 
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Note that if the RAB$B_TMO field contains a value of 0 (and the RAB$L_ 
ROP RAB$V_TMO record option is set) on either a Get or Put service to a 
mailbox device, the operation will complete immediately, rather than waiting 
for another process. For example, a Put service in which the RAB$B_TMO 
field is 0, to a mailbox device will not wait for another process to get the 
record. 

This field is not supported for DECnet operations; it is ignored. 

7.24 RAB$L_UBF 

The user input record area address (UBF) field indicates the location of a 
record or block buffer. This field contains the symbolic address of a work 
area (buffer) within your program. The size of this buffer must be defined in 
the RAB$W_USZ (user record area size) field. 

When you invoke a Get service, this field must contain the buffer address, 
regardless of the record transfer mode (locate or move). This option also 
applies when you issue a Read service for block I/O. However, a Put or Write 
service never needs a user buffer. 

7.25 RAB$W_USZ 

The user record area size (USZ) field indicates the length, in bytes, of the user 
record or block buffer. This field contains a numeric value representing the 
size of the buffer, in the range of 1 through 65,535. 

This buffer area should be large enough to contain the largest record in the 
file. If the buffer is not large enough on an operation with a Get service, VAX 
RMS moves as much of the record as possible into the buffer and returns a 
warning status code. 

The value in this field specifies the transfer length, in bytes, for block I/O 
operations with a Read service and for a Get service to UDF (undefined) 
format sequential files. 

7.26 RAB$I_XAB 

The extended attribute block address (XAB) field contains a symbolic address 
of an XAB control block that you want to use when performing an operation, 
such as a Get service for a terminal device. A value of 0 (the default) indicates 
no XABs for this record stream. 

For certain record operations, you can associate XABs with a RAB to convey 
additional attributes about an operation. (See Part I for a description of an 
XAB.) 
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8 Allocation Control XAB (XABALL) 


The allocation control XAB (XABALL) provides additional control over file or 
area space allocation on disk devices in order to optimize performance. In the 
following descriptions, the terms file and area are synonymous for sequential 
and relative files because these file organizations are limited to a single area 
(Area 0) 


8.1 Summary of Fields 

When VAX RMS uses a XAB to create or extend an area, the following 
XABALL fields duplicate and take precedence over associated fields in the 
related FAB: 

• Allocation quantity (ALQ) field, XAB$L_ALQ, overrides FAB$L_ALQ 

• Bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS 

• Default extension quantity (DEQ) field, XAB$W_DEQ, overrides FAB$W_ 
DEQ 

• The XAB$V_CBT and XAB$V_CTG options of the allocation options field, 
XAB$B—AOP, override the FAB$V_CBT and FAB$V_CTG options of the 
file-processing options field, FAB$L_FOP 

When opening a file or displaying a file's attributes, VAX RMS outputs 
appropriate information to your program using these fields. 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABALL field are presented in Table 8-1. 


Table 8-1 XABALL Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XAB$B_AID 

1 

AREA n 

Area identification number 

XAB$B_ALN 

1 

AREA POSITION 1 

Alignment boundary type 

XAB$I_ALQ 

4 

AREA ALLOCATION 

Allocation quantity 

XAB$B_AOP 

1 

AREA 1 

Allocation options 

XAB$B_BKZ 

1 

AREA BUCKET_SIZE 

Bucket size 

XAB$B_BLN 2 

1 

None 

Block length 

XAB$B_COD 2 

1 

None 

Type code 

XAB$W_DEQ 

2 

AREA EXTENSION 

Default extension quantity 

XAB$I_LOC 

4 

AREA POSITION 

Location 

XAB$L_NXT 

4 

None 

Next XAB address 


1 Field contains options; corresponding FDL equivalents are listed in the description of the field. 

2 Statically initialized field (by the VAX MACRO SXABALL macro) to identify this control block as a XABALL. 
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Table 8-1 (Cont.) XABALL Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XAB$W_RFI 

6 

AREA POSITION FILE_ID 

or FILE—NAME 

Related file identifier 

XAB$W_VOL 

2 

AREA VOLUME 

Related volume number 


Each XABALL field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABALL and $XABALL__ 
STORE macros are described in Appendix B. 


8.2 XAB$B_AID 


VAX RMS uses the area identification number (AID) field to determine which 
area within a file is supported by this XAB. Note that sequential and relative 
files are limited to a single area, area 0. 

The area is identified by a numeric value in the range 0 through 254 (default 
is 0) and is most appropriate for use with index files having multiple areas 
allocated. 

This field corresponds to the FDL attribute AREA n (n indicates the area 
number). 


8.3 XAB$B_ALN 

The alignment boundary type (ALN) field gives you several options on how 
the allocated area is to be aligned. This field is used in conjunction with 
the (XAB$L__LOC) field and with the (XAB$W_RFI) field to provide precise 
positioning control of the area or area extension. The XAB$B_ALN field 
corresponds to the FDL attribute AREA POSITION. 

The (XAB$B_ALN) field is a keyword value field in which an alignment 
boundary option is defined by a symbolic constant value. For example, the 
cylinder boundary option has a symbolic constant value of XAB$C_CYL. 

Note that if no value is defined for this field, VAX RMS assumes the 
XAB$C_ANY option (no additional positioning control desired). Additional 
positioning control is not supported for DECnet operations. 

The following list describes the options for the XAB$B_ALN field: 

Options 

XAB$C_ANY 

Any allocation; specifies that no positioning control over the area is desired. If 
this option is selected, the XAB$L_LOC and XAB$W_RFI fields are ignored. 

This option corresponds to the FDL attribute AREA POSITION NONE. 
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XAB$C_CYL 

Specifies that the area boundary begins at the cylinder number identified by 
the location field, XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION CYLINDER. 

XAB$C_LBN 

Specifies that the area boundary begins at the logical block number identified 
by the location field, XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION LOGICAL. 

XAB$C_RFI 

This option is used only for extending an area. It specifies that the area 
extension starts as close as possible to the file identified by the related-file- 
identification field (XAB$W_RFI), and that the extent begins with the VBN 
specified by the location field, XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION FILE_ID or 
AREA POSITION FILE—NAME. If you try to use this option with DECnet 

operations, VAX RMS automatically substitutes it with the XAB$C_ANY 

option. 

XAB$C_VBN 

This option applies to area extension only. It specifies that the area extension 
starts as close as possible to the virtual block number identified by the 
location field, XAB$L_LOC. 

This option corresponds to the FDL attribute AREA POSITION VIRTUAL. 


8.4 XAB$L_ALQ 


This field defines the number of blocks to be initially allocated to an area 
when it is created using a Create service, or the number of blocks to be added 
to an area when it is explicitly extended using an Extend service (as opposed 
to automatic extension). In both cases, this field overrides the allocation 
quantity in the associated FAB (see Section 5). 

The XAB$L_ALQ field accepts numeric values of up to 4,294,967,295 for 
initial allocation, but the allocation is limited by the number of blocks 
available on the device. 

When you create a new area using the Create service, VAX RMS interprets the 
value in the XAB$L _ALQ field as the number of blocks for the area's initial 
extent. If the value is 0, VAX RMS allocates a minimum number of blocks 
depending on the file organization. For example, VAX RMS allocates only the 
number of blocks needed for the key and area definitions with indexed files. 

When you use either the Create or Extend services, with indexed files VAX 
RMS rounds the allocation quantity value up to the next cluster boundary 
and returns this value to the program in the XAB$L_ALQ field. VAX RMS 
uses this value as the extension value when you extend an existing area using 
the Extend service, unless the program changes the value before invoking the 
Extend service. Note that the value 0 is not acceptable for extending an area. 
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8.5 XAB$B_AOP 

The allocation options (AOP) field lets you specify a particular type of 
allocation. 

This field is a binary options field where one or more options may be selected 
by setting the appropriate bits. Each option is identified by a symbolic bit 
offset and has a mask value; for example, the CBT option has a bit offset of 
XAB$V_CBT and a mask value of XAB$M_CBT. 

The options for the XAB$B_AOP field are summarized in the following list: 

Options 

XAB$V_CBT 

Contiguous best try; indicates that the allocation or extension should use 
contiguous blocks, on a "best effort" basis. This option overrides the FAB$L_ 
FOP field FAB$V_CBT option. 

This option corresponds to the FDL attribute AREA BEST—TRY_ 
CONTIGUOUS. 

XAB$V_CTG 

Contiguous; indicates that the initial allocation extension must use contiguous 
blocks only; the allocation fails if the requested number of contiguous blocks 
is not available. If this is the initial allocation and only a single area is 
specified, the file is marked contiguous. This option overrides the FAB$L_ 
FOP field FAB$V_CTG option. 

This option corresponds to the FDL attribute AREA CONTIGUOUS. 

XAB$V_HRD 

Hard; indicates that if the requested alignment cannot be performed, an error 
will be returned. By default, the allocation is performed as near as possible to 
the requested alignment. 

Note that the XAB$V_HRD option is applicable only to XAB$C_CYL and 
XAB$C_LBN alignment boundary types, specified by the XAB$B_ALN field. 

This option corresponds to the FDL attribute AREA EXACT-POSITIONING. 

XAB$V_ONC 

On cylinder boundary; indicates that VAX RMS is to start the allocation on 
any available cylinder boundary. 

This option corresponds to the FDL attribute AREA POSITION ANY— 
CYLINDER. 


8.6 XAB$B_BKZ 


When creating relative and indexed files, this field is used to specify bucket 
size using numeric values ranging from 0 through 63, representing the 
number of blocks in a bucket. If this argument is omitted, or if a value of 0 
is inserted, VAX RMS uses a default size equal to the minimum number of 
blocks required to contain a single record. For RMS-11 processing, the bucket 
size must be less than or equal to 32 blocks. This field corresponds to the 
FDL attribute AREA BUCKET_SIZE. 
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When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Note that some record types contain 
control bytes and to calculate the overhead you must multiply the number of 
records per bucket by the number of control bytes per record. See the Guide 
to VAX/VMS File Applications for more information. 

The FDL editor can be used to calculate efficient bucket sizes for indexed 
files. (For information about the FDL editor, see the VAX/VMS File Definition 
Language Facility Reference Manual.) 

When you create a file, VAX RMS uses this field as input to determine the 
specified bucket size and upon conclusion, uses the field to output the bucket 
size. Because relative files are limited to one area, this field specifies the size 
for all buckets in the file. For indexed files, you may specify a different size 
for each area using this field in the appropriate XABALL. 

When you open an existing file, VAX RMS uses this field to output the bucket 
size to your program. 

The value in this field overrides the contents of the bucket size field of the 
FAB on a Create service (see Section 5). 

You can specify multiple areas for a single index by having the XAB$B_IAN 
and XAB$B_LAN fields in the key definition XAB (XABKEY) indicate that 
the lowest level of the index and the remainder of that index will occupy 
different areas (defined by different XABALLs). However, the number of 
blocks per bucket (XAB$B_BKZ value) must be the same for the entire index 
of a particular key. If multiple areas are specified for an index and if the 
XAB$B_BKZ values are not the same, VAX RMS returns an error because the 
values for one index must be the same. However, if you specify the XAB$B_ 
BKZ field for at least one area and use the default (0) for the XAB$B_BKZ 
field of a different area (or areas) of the same index, VAX RMS uses the 
largest XAB$B_BKZ value specified among the XABALL control blocks to 
determine the bucket size for that index. 


8.7 XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABALL, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALLEN (this is done by the VAX MACRO $ XABALL macro). 


8.8 XAB$B_COD 


The type code (COD) field is a static field that identifies this control block as 
a XABALL. Once set, this field must not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALL (this is done by the VAX MACRO $XABALL macro). 
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8.9 XAB$W_DEQ 

The default extension quantity (DEQ) field contains the number of blocks to 
be added when automatic extension is required. This number must be in the 
range of 0 through 65,535. If you specify 0, the file will be extended using a 
default extension value determined by VAX RMS. This field corresponds to 
the FDL attribute AREA EXTENSION. 

The value in this field overrides the contents of the default extension quantity 
field of the FAB (see Section 5). 

8.10 XAB$L_LOC 

The location (LOC) field contains a numeric value that indicates the starting 
point for area allocation and corresponds to the FDL attribute AREA 
POSITION. VAX RMS refers to the location field when executing a Create or 
Extend service, but only if the XAB$B_ALN field specifies an alignment 
option. The way the XAB$L_LOC field is used depends on the value 
specified for the XAB$B_ALN field (a binary options field). The starting 
point for the allocation is determined as follows: 

• If the XAB$B_ALN field XAB$C_CYL option is specified, the location 
number is the cylinder number in the range of 0 through the maximum 
cylinder number on the volume, at which the allocation is to start. 

• If the XAB$B_ALN field XAB$C_LBN option is specified, the location 
number is the logical block number in the range of 0 through the 
maximum number of blocks on the volume, at which the allocation is 
to start. 

• If the XAB$B_ALN field XAB$C_VBN or XAB$C_RFI option is specified, 
the location number is the virtual block number in a range from 1 through 
the maximum number of blocks in the file, at which the allocation is 

to start. This use of the XAB$L_LOC field applies only to the Extend 
service. If the number 0 is specified, or if the number is omitted during an 
Extend service, VAX RMS places the file extension as near to the end of 
the file as possible. 

8.11 XAB$I_NXT 

The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 

8.12 XAB$W_RFI 

The related file identification (RFI) field allows you to position files or areas 
of an indexed file close to a specified file. This field corresponds to the FDL 
attribute AREA POSITION FILE_ID or AREA POSITION FILE_NAME. 

This field contains the 3-word file identification value of the related file. 

A value of 0,0,0 (the default) indicates that the current file is to be used. 
Specifying the XAB$B__ALN field XAB$C_RFI option and specifying the 
XAB$W_RFI field as 0,0,0 are equivalent to specifying the XAB$B_ALN field 
XAB$C_VBN option. 
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You can view the file identification of a file using the DCL command 
DIRECTORY with the /FULL qualifier. 

The file is created or extended as near to the specified related file as possible 
at the virtual block number specified by the LOC argument. 

The XAB$W_RFI field is ignored unless the XAB$B_ALN field is set to 
XAB$C_RFI. It is also ignored for DECnet operations. 

8.13 XAB$W_ 

_VOL 

The relative volume number (VOL) field indicates the specific member of a 
volume set upon which the file is to be allocated. This field corresponds to 
the FDL attribute AREA VOLUME. 

This field contains an integer in the range 0 through 255. The default is 0, 
specifying the "current" member of the volume set. 

Note that volume placement will be performed only if an alignment type in 
the XAB$B_ALN field is either XAB$C_CYL or XAB$C_LBN (you cannot 
specify XAB$C_VBN or XAB$C_RFI alignment types). If the XAB$B_ALN 
field contains a value of 0, placement of the file within the volume set will be 
at the discretion of the system, regardless of the contents of the XAB$W_VOL 
field. 
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Date and Time XAB (XABDAT) 


The date and time XAB (XABDAT) block provides extended control of the 
date and time of the file's creation, revision (update), backup, and expiration. 



9.1 




Summary of Fields 

VAX RMS sets certain values for date and time and returns them in XABDAT 
fields for your inspection. You can override these system-supplied values 
through the use of an XABDAT as input to a Create service. Note that date¬ 
time values are expressed in either absolute (positive) or delta (negative) 
format, and several system services are available for date-time conversion 
and use (see Example 3-1 in Part I of this manual and the VAX/VMS System 
Services Reference Manual). 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABDAT field is presented in Table 9-1. 


Table 9-1 XABDAT Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XABSQ—BDT 1 

8 

DATE BACKUP 

Backup date and time 

XAB$B_BLN 2 

1 

None 

Block length 

XABSQ—CDT 1 

8 

DATE CREATION 

Creation date and time 

XAB$B_COD 2 

1 

None 

Type code 

XAB$Q_EDT 

8 

DATE EXPIRATION 

Expiration date and time 

XAB$I_NXT 

4 

None 

Next XAB address 

XABSQ—RDT 1 

8 

DATE REVISION 

Revision date and time 

XAB$W_RVN’ 

2 

FILE REVISION 

Revision number 


1 Field cannot be initialized by the VAX MACRO SXABDAT macro. 

2 Statically initialized field (by the VAX MACRO SXABDAT macro) to identify this 
control block as a XABDAT. 


Table 9-2 describes how the fields of the XABDAT block are used by the VAX 
RMS file-processing services. 
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Table 9-2 Services and the XABDAT Control Block 


Service 

XAB$Q BDT 

XAB$Q_CDT 

XAB$Q_EDT 

XAB$Q_RDT, XAB$W_RVN 

Close 

Not used 

Not used 

Not used 

Not used 

Create 

Input 

Input 

Input 

Input 1 

Display 

Output 

Output 

Output 

Output 

Erase 

Not used 

Not used 

Not used 

Not used 

Extend 

Not used 

Not used 

Not used 

Not used 

Open 

Output 

Output 

Output 

Output 


^he XAB$Q_RDT field for a Create service is superseded by the current date and time on a Close service. 
Use the XABRDT block to specify the XAB$Q_RDT field (see Section 13). 


The following notes apply to the use of XABDAT fields by VAX RMS services: 

1 If the user specifies the XAB$Q_CDT or XAB$Q_RDT field in the 
XABDAT as 0 (either explicitly or by default) and if the specified field 

is used as an input field by the file-processing service, it will be replaced 
with the current date and time. 

2 If the Create service is invoked with a FAB that specifies the FAB$L_FOP 
field FAB$V_CIF (create-if) option and if the file to be created already 
exists, the Create service is processed like an Open service and the fields 
listed above are output fields. 

Each XABDAT field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABDAT and $XABDAT_ 
STORE macros are described in Appendix B. 


9.2 XAB$Q_BDT 


The backup date and time (BDT) field contains a 64-bit binary value 
expressing the date and time when the file was most recently backed up. 
This field corresponds to the FDL attribute DATE BACKUP. 

Note that this field is limited to a granularity of 1 second for remote files. 


9.3 XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABDAT in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DATLEN (this is done by the VAX MACRO $XABDAT macro). 
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9.4 

XAB$Q_CDT 

The creation date and time (CDT) field contains a 64-bit binary value 
expressing the date and time when the file was created. This field corresponds 
to the FDL attribute DATE CREATION. 

Note that this field is limited to a granularity of 1 second for remote files. 

9.5 

X A B$B_C O D 

The type code (COD) field is a static field that identifies this control block 
as an XABDAT. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DAT (this is done by the VAX MACRO $XABDAT macro). 

9.6 

XAB$Q_EDT 

The expiration date and time (EDT) field contains a 64-bit binary value that 
indicates the date and time after a file residing on a disk device may be 
considered for deletion by the system manager. For files residing on magnetic 
tape devices, the XAB$Q_EDT field sets the date and time after which you 
can overwrite the file. This field corresponds to the FDL attribute DATE 
EXPIRATION. 

Note that this field is limited to a granularity of 1 second for remote files. 

9.7 

XAB$I_NXT 

The next XAB address (NXT) field contains a symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 

9.8 

XAB$Q_RDT 

The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time when the file was last updated. This field 
corresponds to the FDL attribute DATE REVISION. 

Note that this field is limited to a granularity of 1 second for remote files. 

9.9 

XAB$W_RVN 

The revision number (RVN) field contains a numeric value that indicates 
the number of times this file was opened for write operations. This field 
corresponds to the FDL attribute FILE REVISION. 
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1 0 File Header Characteristic XAB (XABFHC) 


The file header characteristic XAB (XABFHC) contains information about a file 
that is stored in the file header. VAX RMS copies the file characteristics into 
this XAB whenever an Open or Display service executes. The XABFHC fields 
are then available for you to examine during processing. 

Note that for sequential files shared with the user-process interlocking share 
option (FAB$V_UPI bit set), the values in the end-of-file block (XAB$L_ 
EBK), first free byte in the end-of-file block (XAB$W_FFB), and longest record 
length (XAB$W_LRL) fields correspond to the values at the time of the last 
Close or Flush service. 

On a Create service, only the longest record length (XAB$W_LRL) field of this 
XAB is used as input, and then only if the record format is not fixed length. 
All other fields are used only as output from the VAX RMS services. 


10.1 Summary of Fields 

The symbolic offset, size, and a brief description of each RAB field are 
presented in Table 10-1. Note that many of these fields are also available in 
the FAB. 


Table 10-1 XABFHC Fields 


Field Offset 

Size 

(bytes) 

Description 

XABSB.ATR 1 

1 

Record attributes; equivalent to FAB$B_RAT 

XABSB-BKZ 1 

1 

Bucket size; equivalent to FAB$B_BKS 

XAB$B_BLN 2 

1 

Block length 

XAB$B_COD 2 

1 

Type code 

XABSW-DXQ 1 

2 

Default file extension quantity; equivalent to 
FAB$W_DEQ 

XABSL—EBK 1 

4 

End-of-file block 

XABSW—FFB 1 

2 

First free byte in the end-of-file block 

XABSW—GBC 1 

2 

Default global buffer count 

XAB$I_HBK 1 

4 

Highest virtual block in the file; equivalent to 
FAB$L_ALQ 

XABSB—HSZ 1 

1 

Fixed-length control header size; equivalent to 
FAB$B_FSZ 

XABSW—LRL 1 

2 

Longest record length 


1 Field cannot be initialized by the VAX MACRO SXABFHC macro. 

2 Statically initialized field (by the VAX MACRO $XABFHC macro) to identify this 
control block as a XABFHC. 
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Table 10-1 (Cont.) XABFHC Fields 


Field Offset 

Size 

(bytes) 

Description 

XABSW-MRZ 1 

2 

Maximum record size; equivalent to FAB$W_ 
MRS 

XAB$I_NXT 

4 

Next XAB address 

XABSB—RFO 1 

1 

File organization and record format; combines 
FAB$B_RFM and FAB$B_ORG 

XAB$I_SBN 1 

4 

Starting logical block number for the file if it is 
contiguous; otherwise this field is 0 

XAB$W_ 

VERLIMIT 1 

2 

Version limit for the file 

1 Field cannot be initialized by the VAX MACRO SXABFHC macro. 


Each XABFHC field is described below. There are no FDL equivalents for 
the XABFHC fields. Unless indicated otherwise, each field is supported for 
DECnet operations using remote files with a VAX/VMS system as the remote 
node. Note that the words "DECnet operations" in the following descriptions 
refer to remote file operations between two VAX/VMS systems. See the 
VAX/VMS Networking Manual for information about the support of VAX RMS 
options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABFHC and $XABFHC_ 
STORE macros are described in Appendix B. 


XAB$B_ATR 

The record attributes (ATR) field indicates the type of record attributes 
(special control information) associated with each record in this file. This field 
is equivalent to the FAB$B_RAT field. 

This field is a binary options field where each record attribute has a 
corresponding bit assignment. Options are identified using mnemonics. 

Each option in the field has its own symbolic bit offset and constant value. 
For example, the CR record attribute has a symbolic bit offset of XAB$V_CR 
and a mask value of XAB$M_CR. The record attribute options are described 
in the following list: 

Options 

XAB$V_BLK 

Records do not cross block boundaries in sequential files. 

XAB$V_CR 

Each record is preceded by a line feed and followed by a carriage return, 

XAB$V_FTN 

Each record contains a FORTRAN (ASA) carriage return in the first byte. 

XAB$V_PRN 

Print file format. 

For more information, refer to Section 5, FAB$B_RAT. 
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10.3 

XAB$B_BKZ 

The bucket size (BKZ) field specifies the number of blocks in each bucket of 
the file. It is equivalent to the FAB$B_BKS (or XAB$B_BKZ) field and is used 
only for relative or indexed files. 

This field contains a numeric value in the range of 0 to 63. Refer to Section 5, 
FAB$B_BKS, or Section 8, XAB$B_BKZ, for more information about the 
XAB$B_BKZ field. 

10.4 

XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABFHC, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHCLEN (this is done by the VAX MACRO $XABFHC macro). 

10.5 

XAB$B_COD 

The type code (COD) field is a static field that identifies this control block 
as an XABFHC. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHC (this is done by the VAX MACRO $ XABFHC macro). 

10.6 

XAB$W_DXQ 

The default file extension quantity (DXQ) field specifies the number of blocks 
to be added when a disk file is extended automatically. This automatic 
extension occurs whenever your program performs a Put or Write service and 
the currently allocated file space is exhausted. 

This field is equivalent to the FAB$W_DEQ (or XAB$W_DEQ) field; it 
contains a numeric value in the range 0 through 65,535, which is rounded up 
to the value of the next cluster boundary. 

Refer to Section 5, FAB$W_DEQ or Section 8, XAB$W_DEQ for more 
information about the XAB$W_DXQ field. 

10.7 

XAB$I_EBK 

The end-of-file block (EBK) field contains the virtual block number where 
the last record was written to the file. This value is meaningful only for 
sequential and relative files. 

10.8 

XAB$W_FFB 



The first free byte in the end-of-file block (FFB) field contains the byte location 
in the end-of-file block where the next record will be written. This value is 
meaningful only for sequential and relative files. 
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10.9 XAB$W_GBC 


The default global buffer count (GBC) field contains the current global buffer 
count for this file. For more information, refer to Section 5, FAB$W_GBC. 

This field is not supported for DECnet operations; it is ignored. 


10.10 XAB$I_HBK 


The highest virtual block (HBK) field contains the virtual block number 
currently allocated to this file. It is equivalent to the FAB$L__ALQ field after 
a Create, Open, or Display service executes. The difference between XAB$L_ 
HBK minus XAB$L _EBK equals the number of blocks available in this file to 
contain additional records for sequential files without extending the file. 


10.11 XAB$B_HSZ 


The fixed length control header size (HSZ) field indicates the length of the 
fixed portion for records in the variable with fixed-length control record 
format. It is equivalent to the FAB$B_FSZ field. 

This field contains a numeric value in the range of 1 to 255 that indicates, in 
bytes, the size of the fixed-length control area. This field is not applicable to 
indexed files. 

For additional information, see Section 5, FAB$B_FSZ. 


10.12 XAB$W_LRL 


The longest record length (LRL) field contains a numeric value that indicates 
the longest record currently in the file, in bytes. This value is meaningful 
only for sequential files. 


10.13 XAB$W_MRZ 


The maximum record size (MRZ) field indicates the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size for relative files. It is equivalent to the FAB$W_MRS field. 

This field contains a numeric value in the range applicable to the file type and 
record format (see Table 5-4), in bytes. 

For fixed-length records, the value represents the actual size of each record in 
the file. 

For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size. 

For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 

For additional information, refer to Section 5, FAB$W_MRS. 
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10.14 XAB$L_NXT 

The next XAB address (NXT) field contains a symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 


10.15 XAB$B_RFO 

The file organization and record format (RFO) field combines the FAB$B_ 
RFM and FAB$B_ORG fields using an inclusive OR. 

Record formats are listed below. 


Record Format 

Description 

FIX 

Fixed-length 

STM 

Stream, delimited by FF, VT, LF, or CR LF 

STMCR 

Stream, delimited by CR 

STMLF 

Stream, delimited by LF 

UDF 

Undefined 

VAR 

Variable-length 

VFC 

Variable-length with fixed control area 

The file organizations 

are listed below. 

File Organization 

Description 

IDX 

Indexed sequential 

REL 

Relative 

SEQ 

Sequential 


For more information, refer to Section 5, FAB$B_ORG and FAB$B_RFM. 


10.16 XAB$I_SBN 

The starting logical block number (SBN) field contains the starting logical 
block number for a contiguous file; if the file is not contiguous, this field 
contains 0. 


10.17 XAB$W_VERLIMIT 

The file version limit (VERLIMIT) field contains the version limit for this file. 
This value is not available if the file was opened by file ID. 

This field is not supported for DECnet operations; it is ignored. 
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1 1 Key Definition XAB (XABKEY) 


The key definition XAB (XABKEY) defines the characteristics of a key in an 
indexed file. Before you create an indexed file, you must set the contents of 
the XABKEY fields. Furthermore, for each key that you want the file to have, 
you must provide one XABKEY. Because every indexed file must have at least 
one key (the primary key), you will always require at least one XABKEY. 

When you invoke an Open or Display service for an existing indexed file, you 
can use XABKEYs if you want VAX RMS to provide your program with one or 
more of the key definitions specified when the file was created. Alternatively, 
the summary XAB (see Section 14) provides the number of keys, number of 
allocated areas, and the prologue version assigned to the file. 


11.1 Summary of Fields 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABKEY field are presented in Table 11-1. 


Table 11-1 XABKEY Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XABSB-BLN 1 

1 

None 

Block length 

XABSB—COD 1 

1 

None 

Type code 

XAB$B_DAN 

1 

KEY DATA_AREA 

Data bucket area number 

XAB$B_DBS 2 

1 

None 

Data bucket size 

XAB$W_DFL 

2 

KEY DATA_FILL 

Data bucket fill size 

XAB$B_DTP 

1 

KEY TYPE 3 

Data type of the key 

XAB$L_DVB 2 

4 

None 

First data bucket virtual block number 

XAB$B_FLG 

1 

KEY 3 

Key options flag 

XAB$B_IAN 

1 

KEY INDEX_AREA 

Index bucket area number 

XAB$B_IBS 2 

1 

None 

Index bucket size 

XAB$W_IFL 

2 

KEY INDEX-FILL 

Index bucket file size 

XAB$L_KNM 

4 

KEY NAME 

Key name buffer address 

XAB$B_LAN 

1 

KEY LEVEL 1—INDEX_AREA 

Lowest level of index area number 

XAB$B_LVL 2 

1 

None 

Level of root bucket 

XAB$W_MRL 2 

2 

None 

Minimum record length 

XAB$B_NSG 2 

1 

None 

Number of key segments 

XAB$B_NUL 

1 

KEY NULL-VALUE 

Null key value 


Statically initialized field (by VAX MACRO SXABKEY macro) to identify this control block as an XABKEY. 

2 Field cannot be initialized by the VAX MACRO $XABKEY macro. 

3 Field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 11-1 (Cont.) XABKEY Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$W_POSn 

2 

KEY POSITION and 
SEGn_POSITION 

Key position, 

XAB$W_POSO to 

XAB$W_POS7 

XAB$B_ 

PROLOG 

1 

KEY PROLOG 

Prologue level 

XAB$B_REF 

1 

KEY n 

Key of reference 

XAB$I_RVB 2 

4 

None 

Root bucket virtual block number 

XAB$B_SIZn 

1 

KEY LENGTH and 
SEGn_LENGTH 

Key size XAB$B_SIZO to 

XAB$B_SIZ7 

XAB$B_TKS 2 

1 

None 

Total key field size 

2 Field cannot be initialized by the VAX MACRO $XABKEY 

macro. 


Each XABKEY field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABKEY and $XABKEY_ 
STORE macros are defined in Appendix B. 


11.2 XAB$B_BLN 


The block length (BLN) field is a static field that defines the length of the 
XABKEY, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_KEYLEN (this is done by the VAX MACRO $XABKEY macro). 


11.3 XAB$B_COD 


The type code (COD) field is a static field that identifies this control block 
as an XABKEY. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_KEY (this is done by the VAX MACRO $ XABKEY macro). 
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XABSB—DAN 

11.4 XAB$B_DAN 

The data bucket area number (DAN) field contains a numeric value in the 
range 0 through 254, representing an identification number contained in the 
XAB$B_AID field of a XABALL present in the same XAB chain. The default 
is 0, that is, area 0. This field corresponds to the FDL attribute KEY DATA— 
AREA. 

You must specify a value for this field in order to identify the area of the file 
that the data buckets are to reside in only when: 

• You create a new indexed file. 

• You use allocation XABs to define areas (see Section 8). 

When an XABKEY describes the primary key, the data level of the index 
consists of buckets that contain the actual data records of the file. However, 
when the key definition describes an alternate key, the data level of the index 
consists of buckets in which VAX RMS maintains pointers to the actual data 
records. 

11.5 XAB$B_DBS 

After an Open or Display service, the data bucket size (DBS) field contains the 
size of the data level (level 0) buckets, in virtual blocks, for the key described 
by the XAB. 

11.6 XAB$W_DFL 

The data bucket fill size (DFL) field contains a numeric value that indicates 
the maximum number of bytes (of data) in a data bucket. The largest possible 
fill size is the bucket size, in blocks, multiplied by 512. The default value is 

0, which is interpreted by VAX RMS as the maximum available space (that 
is, no unused space). If the specified size is not 0, but is less than one-half of 
the bucket size (in bytes), then the fill size used will be one-half of the bucket 
size. This field corresponds to the FDL attribute KEY DATA_FILL (which is 
expressed as a percentage). 

When you create an indexed file, you use this field to specify the number 
of bytes of data you want in each data level bucket. If you specify a value 
that is less than the actual bucket size, the data buckets will contain some 
amount of free space. At run time, VAX RMS uses the fill size specified when 
the file was created only if the RAB$L_ROP (record-processing options) field 
RAB$V_LOA option is specified in the RAB; otherwise, VAX RMS fills the 
buckets. 

When an XABKEY describes the primary key, the XAB$W_DFL field describes 
the space in the buckets containing actual user data records. When the 
XABKEY describes an alternate key, the XAB$W_DFL field describes the 
space in the buckets containing pointers to the user data records. 

It is advantageous to use the XAB$W_DFL field if you expect to execute 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of records (bucket 
splitting) by specifying less than the maximum bucket fill size when you 
create the file. To use the free space reserved in the buckets, programs that 
execute Put or Update services on the file should not specify the RAB$L_ 
ROP field RAB$V_LOA option. 
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XAB$B_DTP 


11.7 XAB$B_DTP 

The XAB$B_DTP field specifies the key data type and the key sort order, 
ascending or descending. This field corresponds to the FDL attribute KEY 
TYPE. 

In this keyword value field, each key data type option is defined by a 
symbolic value. If the key sort order is descending, the letter D is prefixed to 
the symbolic value; if the sort order is ascending, the prefix is omitted. For 
example, a XAB$B_DTP field having the value XAB$C_DBN2 is an unsigned, 
2-byte binary number which is sorted in descending order. On the other 
hand, a XAB$B_DTP field having the value XAB$C_BN2 is an unsigned, 
2-byte binary number which is sorted in ascending order. 

Only one option can be specified and is identified by a symbolic constant 
value; for example, the STG (string) option has a constant value of XAB$C__ 
STG. 

The options for XAB$B_DTP field are listed in the following chart: 


Keyword 

Data type 

Sort order 

XAB$C_BN2 

Unsigned 2-byte binary 

Ascending 

XAB$C_DBN2 

Unsigned 2-byte binary 

Descending 

XAB$C_BN4 

Unsigned 4-byte binary 

Ascending 

XAB$C_DBN4 

Unsigned 4-byte binary 

Descending 

XAB$C_BN8 

Unsigned 8-byte binary 

Ascending 

XAB$C_DBN8 

Unsigned 8-byte binary 

Descending 

XAB$C_IN2 

Signed 2-byte integer 

Ascending 

XAB$C_DIN2 

Signed 2-byte integer 

Descending 

XAB$C_IN4 

Signed 4-byte integer 

Ascending 

XAB$C_DIN4 

Signed 4-byte integer 

Descending 

XAB$C_IN8 

Signed 8-byte integer 

Ascending 

XAB$C_DIN8 

Signed 8-byte integer 

Descending 

XAB$C_PAC 

Packed decimal string 

Ascending 

XAB$C_DPAC 

Packed decimal string 

Descending 

XABSC—STG 1 

Left-justified string of 
unsigned, 8-bit bytes 

Ascending 

XAB$C_DSTG 

Left-justified string of 
unsigned, 8-bit bytes 

Descending 

^his is the default value. 


The string data type may consist of from one to eight disjoined key field 
segments that collectively comprise the key (see XAB$W_POSO through 
XAB$B_POS7 field and XAB$B_SIZ0 through XAB$B„SIZ7 field). 

Integer, binary, and packed decimal key fields must be a contiguous set of 
bytes. 

The null value (that is, XAB$V_NUL option in XAB$B_FLG field is set) for 
integer, binary, and packed decimal data types is 0, and the XAB$B_NUL 
field is ignored (see XAB$B_FLG and XAB$B_NUL). 
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The formats of the binary and integer key field data types are presented 
below. 


Key Type 

Format 





XAB$C_BN2 

LSB 

at 

A, 

MSB 

at A+1 



XAB$C_DBN2 

LSB 

at 

A, 

MSB 

at A+1 



XAB$C_BN4 

LSB 

at 

A, 

MSB 

at A+3 



XAB$C_DBN4 

LSB 

at 

A, 

MSB 

at A+3 



XAB$C_BN8 

LSB 

at 

A, 

MSB 

at A+7 



XAB$C_DBN8 

LSB 

at 

A, 

MSB 

at A+7 



XAB$C_IN2 

LSB 

at 

A, 

MSB 

and sign 

at 

A+1 

XAB$C_DIN2 

LSB 

at 

A, 

MSB 

and sign 

at 

A+1 

XAB$C_IN4 

LSB 

at 

A, 

MSB 

and sign 

at 

A+3 

XAB$C_IN4 

LSB 

at 

A, 

MSB 

and sign 

at 

A+3 

XAB$C_IN8 

LSB 

at 

A, 

MSB 

and sign 

at 

A+7 

XAB$C_DIN8 

LSB 

at 

A, 

MSB 

and sign 

at 

A+7 


A packed decimal string is a contiguous sequence of bytes and is specified 
by two attributes: the address (A) of the first byte of the string and a length 
(L) that is the number of digits in the packed decimal. The bytes of a packed 
decimal are divided into two 4-bit fields that must contain decimal digits, 
except for the first four bits (0 through 3) of the last (highest addressed) byte, 
which must contain a sign. The representation for the digits and signs is 
shown below. 


Digit or Sign 

Decimal Value 

Hex Value 

0 

0 

0 

1 

1 

1 

2 

2 

2 

3 

3 

3 

4 

4 

4 

5 

5 

5 

6 

6 

6 

7 

7 

7 

8 

8 

8 

9 

9 

9 

+ 

10, 12, 14, or 15 

A, C, E, OR F 

- 

11 or 13 

B or D 


The preferred sign representation is 12 for plus ( + ) and 13 for minus (-). 
The length (L) is the number of digits in the packed decimal string (not 
counting the sign) and must be in the range 0 through 31. When the number 
of digits is even, an extra 0 digit must appear in the last four bits (4 through 
7) of the first byte. Again the length in bytes of the packed decimal is L/2 + 
1. The value of a 0-length packed decimal is 0; it contains only the sign byte, 
which also includes the extra 0 digit. 
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The address. A, of the packed decimal specifies the byte containing the most 
significant digit in its high order. Digits of decreasing significance are assigned 
to increasing byte addresses and from high to low within a byte. Thus, +123 
has length 3 and is represented as follows: 


A 


A+l 


7 4 3 0 


1 

2 

3 

12 


ZK-873-82 


and -12 has length 2 and is represented as follows: 


7 4 3 0 


0 

1 

2 

13 


ZK-874-82 


11.8 XAB$I_DVB 


After an Open or Display service, the DVB field contains the starting virtual 
block number of the first data level bucket for the key described by the XAB. 


11.9 XAB$B_FLG 


The key options flag (FLG) field specifies the following: 

• if duplicate keys are permitted in the file 

• if a key value can change 

• if data is compressed 

• various options that apply only to string keys. 

Primary key values cannot change, but alternate key values may change, 
depending on application requirements. Primary and alternate keys may be 
duplicated depending on the key field and the application. An alternate key 
field is more likely than a primary key field to use duplicates. 

This field is a binary options field where each key characteristic has a 
corresponding bit assignment. Multiple key characteristics can be associated 
with each key (multiple bits can be set on). Each option in the field has 
its own symbolic bit offset and mask value. For example, the CHG key 
characteristic has a symbolic bit offset of XAB$V_CHG and a mask value of 
XAB$M_CHG. 

When you create an indexed file and are defining a string key, you can 
optionally specify the XAB$V_IDX_NCMPR, XAB$V_KEY_NCMPR, and 
XAB$V_NUL options. 
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These are the options for the XAB$B_FLG field: 

Options 

XAB$V_CHG 

The key value within the record in the file can be changed by a program 
during an Update service. This option can be specified only for alternate 
keys. 

This option corresponds to the FDL attribute KEY CHANGES. 

XAB$V_DAT_NCMPR 

Do not compress data. This option can be specified to override compression 
of data for Prolog 3 files for the primary key, that is, when XAB$B_REF is 0. 

This option corresponds to the FDL attribute KEY DATA—RECORD— 
COMPRESSION. 

This option is not supported for DECnet operations; it is ignored. 

XAB$V_DUP 

The key value within the record in the file may have the same key value as 
another record (or other records) within the file. 

This option corresponds to the FDL attribute KEY DUPLICATES. 

XAB$V_I DX_NCM PR 

Do not compress index. This option can be specified to override compression 
of keys in the index for Prolog 3 files. This option is only valid if a string key 
is being defined. 

This option corresponds to the FDL attribute KEY INDEX—COMPRESSION. 
This option is not supported for DECnet operations; it is ignored. 

XAB$V_KEY—NCMPR 

Do not compress key. This option can be specified to override compression of 
each key for Prolog 3 files. For a primary key (XAB$B_REF is 0), the primary 
keys at the data level are not compressed; for each alternate key (XAB$B_REF 
is greater than 0), the secondary index data records (SIDRs) that point to the 
data record location are not compressed. This option is only valid if a string 
key is being defined. 

This option corresponds to the FDL attribute KEY DATA—KEY- 
COMPRESSION. 

This option is not supported for DECnet operations; it is ignored. 

XAB$V_NUL 

When set, this bit refers VAX RMS to the XAB$B_NUL field to determine 
whether or not you have defined a null character for removing records from 
the related alternate index. This option can be specified only for alternate key 
indexes using string type keys and it corresponds to the FDL attribute KEY 
NULL-KEY. 
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The defaults and combinations of allowing changeable key values (XAB$V__ 
CHG option) and duplicate key values (XAB$V_DUP option) depend on 
whether a primary or alternate key is being defined by this XABKEY. The 
allowed combinations and defaults for duplicate and changeable key values 
are described below. 


Combinations 

Primary Key 

Alternate 

Key 

XAB$V_CHG and XAB$V_DUP both set 

Error 

Allowed 

XAB$V_CHG set, XAB$V_DUP clear 

Error 

Allowed 

XAB$V_CHG clear, XAB$V_DUP set 

Allowed 

Allowed 

XAB$V_CHG and XAB$V_DUP both clear 

Default 

Default 


Thus, the defaults for a primary key are: 

• Duplicate keys are not allowed 

• Key values cannot change 

If the XABKEY control block is not initialized by the VAX MACRO $XABKEY 
macro, then the defaults for alternate keys are the same as for primary keys 
and null key values are not used. However, if the XABKEY control block 
is initialized by the VAX MACRO $XABKEY macro, then the defaults for 
alternate keys are: 

• Duplicate key values are allowed 

• Key values can change 

• No null key values 

These defaults are applied only if the entire XAB$B_FLG field is defaulted. 

Note that VAX RMS supports alternate indexes that prohibit duplicate key 
values but do allow key values to change for Update services. Older versions 
of RMS-11 (in contrast to VAX RMS) do not allow this particular combination 
of attributes for alternate indexes. This factor should be considered when you 
create files with VAX RMS that may also be processed by RMS-11. 


11.10 XAB$B_IAN 


The index bucket area number (IAN) field contains a numeric value in the 
range 0 through 254, representing an area identification number contained in 
the XAB$B_AID field of an XABALL present in the same chain. The default 
is 0 (that is, area 0). This field corresponds to the FDL attribute KEY INDEX— 
AREA. 

When you create an indexed file, you use this argument to specify the area of 
the file that the index buckets are to reside in only when both of the following 
are true: 

• You are creating a new indexed file. 

• You are using allocation XABs to define areas. 
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When the XABKEY describes the primary key, the index level of the index 
consists of all levels of the tree-structured primary index down to and 
including the level containing pointers to the user data records themselves. 
However, when the key definition describes an alternate key, the index 
level of the index comprises all levels of the tree-structured alternate index 
down to, but not including, the level containing buckets in which VAX RMS 
maintains pointer arrays describing the user data records. See the XAB$B_ 
LAN field for a description of how to place the lowest level of the index in a 
location separate from the higher levels. 

11.11 XAB$B_IBS 

After an Open or Display service, the index bucket size (IBS) field contains 
the size of the index level (level 1 to n) buckets, in virtual blocks, for the key 
described by the XAB. 

11.12 XAB$W_IFL 

The index bucket fill size (IFL) field contains a numeric value representing 
the maximum number of bytes in an index bucket. The maximum possible 
fill size is the bucket size, in blocks, multiplied by 512. The default value 
is 0, which is interpreted by VAX RMS as meaning the maximum available 
space (that is, no unused space). If the specified size is not 0, but is less than 
one-half of the bucket size (in bytes) then the fill size used will be one-half of 
the bucket size. This field corresponds to the FDL attribute KEY INDEX—FILL 
(which is expressed as a percentage). 

When you create an indexed file, you use this argument to specify the 
number of bytes you want in each index bucket. If you specify less than 
the total possible bucket size, you indicate that the index buckets are to 
contain some amount of free space. At run time, VAX RMS uses the fill size 
specified at creation time if the LOA option is specified in the RAB$L—ROP 
(record-processing options) field of the RAB; otherwise, VAX RMS fills the 
buckets. 

When an XABKEY describes the primary key, the XAB$W_IFL field describes 
the space in the buckets in all levels of the primary index down to and 
including the level containing pointers to the user data records. When an 
XABKEY describes an alternate key, the XAB$W_IFL field describes the space 
in the buckets in all levels of the alternate index down to, but not including, 
the level containing buckets in which VAX RMS maintains pointer arrays 
describing the user data records. 

It is advantageous to use the XAB$W__IFL field if you expect to perform 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of index records (bucket 
splitting) by specifying less than the maximum bucket fill size when a file is 
created. To use the free space thereby reserved in the buckets, programs that 
perform Put or Update services on the file should not specify the RAB$L — 
ROP field RAB$V_LOA option. 
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11.13 XAB$I_KNM 

The key name buffer address (KNM) field contains the symbolic address of a 
buffer that is available for assigning a user-specified name to the key being 
defined. The name buffer must be at least 32 bytes in length and you may 
use any 32-character string you choose to name the key field. 

If the default value is taken (0), VAX RMS assumes no name is to be assigned 
to the key. VAX RMS does not use this string but retains it in the file as part 
of the key definition information for documentation purposes. 


11.14 XAB$B_LAN 

The lowest level of index area number (LAN) field contains a numeric 
value, in the range 0 through 254 representing an area identification number 
contained in the XAB$B_AID field of an XABALL present in the same XAB 
chain. If the XAB$B_LAN field is not specified (that is, if the value is 0), the 
value in the XAB$B_IAN field is used as a default; in other words, the lowest 
level of the index will occupy the same area of the file as the remainder of 
the index. This field corresponds to the FDL attribute KEY LEVEL1_INDEX_ 
AREA. 

This field permits you to separate the lowest level (level 1) of the index from 
all higher levels (levels 2+) of the index in an indexed file; you can use the 
XAB$B_LAN field to specify an area of the index wherein the lowest level 
of the index will reside, separate from the area (or areas) specified by the 
XAB$B_IAN field (wherein levels of the index will reside). See XAB$B_IAN 
for additional information. 

You can specify the XAB$B_LAN field only when both of the following 
conditions exist: 

• You are creating a new indexed file. 

• You are using allocation XABs to define areas. 

Note that the area specified by the XAB$B_LAN field must have the same 
bucket size as the area specified by the XAB$B_IAN field. 


11.15 XAB$B_LVL 

Following an Open or Display service, the level of root bucket (LVL) field, 
contains the level of the root bucket for the key described by the XAB. 


11.16 XAB$W_MRL 


Following an Open or Display service, the minimum record length (MRL) 
field contains the minimum record length (in bytes), needed to contain the 
key field for the key described by the XAB. 

If the key described by the XAB is the primary key (XAB$B_REF is 0), then a 
record must be equal to or greater than the minimum record length returned 
in XAB$W_MRL to be inserted or updated in the file. 
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If the key described by the XAB is an alternate key (XAB$B_REF is greater 
than 0), then a record must be equal to or greater than the minimum record 
length returned in the XAB$W_MRL field to be recorded in the associated 
index for that alternate key. 


11.17 XAB$L_NXT 

The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 


11.18 XAB$B_NSG 

Following an Open or Display service, the number of key segments (NSG) 
field contains the number of key segments that make up the key field for the 
key described by the XAB (see XAB$W_POSO through XAB$B_POS7 field). 


11.19 XAB$B_IMUL 

Normally, VAX RMS updates all indexes to reflect the values in the 
corresponding key fields of the records written to an indexed file. The 
XAB$B_NUL field permits you to instruct VAX RMS not to make an entry 
in an alternate index if a record being entered in an indexed file contains a 
specified null alternate key value. To specify the XAB$B_NUL field, three 
conditions must be satisfied: 

• The XABKEY must define an alternate key. 

• The XAB$B_FLG field XAB$V_NUL option be set when you create the file 
(see XAB$B_FLG). 

• The key data type must be string. 

You can use any ASCII character in the null (NUL) field if you are defining 
a string-type alternate keys. The default null value for string-type alternate 
keys is 0 and nonstring keys always use 0 for the null value. This field 
corresponds to the FDL attribute KEY NULL—VALUE. 


11.20 XAB$W_POSO through XAB$B_POS7 

There are two types of keys, simple keys and segmented keys. 

A simple key may be used with any data type, including the string data type, 
and it includes one or more contiguous bytes. For simple keys, the first byte 
of the key position field contains a numeric variable whose value relative to 
0 defines the the starting position of the key. The remaining bytes contain 
zeroes. 

Segmented keys include 2 through 8 strings of key data (segments) and they 
can only be used with string data type key fields. The key segments need 
not be contiguous nor must they be in a particular order. Key segments 
may overlap except for primary keys used with Prolog 3 files. If your 
application requires overlapping key segments in a Prolog 3 file, consider 
using an alternate segmented key. If you must have a primary key with 
overlapping segments, VAX RMS requires you to use either a Prolog 2 or 
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XAB$W_POSO through XAB$B_POS7 


Prolog 1 structure (which it will automatically assign if the XAB$B_PROLOG 
field is not specified.) 

For segmented keys, the first word of the key position field specifies the 
starting position of the first segment and each succeeding byte specifies the 
starting position of the remaining segments. When processing records that 
contain segmented keys, VAX RMS regards a segmented key field as a single, 
logically contiguous string beginning with the first segment and ending with 
the last. 

You should note that the XAB$W_POSO through XAB$B_POS7 and the 
XAB$B_SIZ0 through XAB$B_SIZ7 (key size) fields must define an equal 
quantity of key position values and key size values. 


11.21 XAB$B_PROLOG 

The prologue (PROLOG) field defines the version or structure level of the file 
index. It contains a numeric value in the range of 0 to 3 and corresponds to 
the FDL attribute KEY PROLOG. 

The XAB$B_PROLOG field is input to the Create service, and it is returned 
by the Display and Open services. 

This field must only be used when defining a primary key (when XAB$B_REF 
is 0). 

Prolog 3 is the default prologue level, unless the primary key contains 
overlapping segments. VAX RMS examines the key characteristics and 
determines the correct prologue structure to apply to the file. If the XAB$B_ 
PROLOG field is not specified (that is, if the value is 0), the process default 
prologue level is examined, then the system default prologue level is used. 
These default values are set by the DCL command SET RMS_DEFAULT 
/PROLOG. 

You should not specify a prologue level 1 because VAX RMS will decide 
whether a Prolog 1 or Prolog 2 file should be created, depending on the key 
types defined for the file. If you want to select a prologue level other than 
Prolog 3, you should select either 0 or 2. 

For more detailed information regarding the options for selecting a specific 
prologue level, see Part III, $ CREATE. 

This field is not supported for DECnet operations; the default prologue in 
effect at the remote node is used. 


11.22 XAB$B_REF 

The key of reference (REF) field defines a key as either the primary key or 
some alternate key. This field corresponds to the FDL attribute KEY n (n is 
the number of the key being defined). 

This field contains a numeric value in the range 0 through 254. A value of 
0 indicates this is the primary key; a value of 1 indicates the first alternate 
key; a value of 2 indicates the second alternate key, and so on. The order in 
which the XABKEYs occur is irrelevant. 
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Note that VAX RMS can process an indexed file with 255 defined keys; each 
defined key field, however, has an associated cost in processing and I/O 
time. The time required to build and maintain the index for the key field 
and the disk storage required to contain the index for each key field should 
be considered when you decide whether the field should be an alternate key 
field. A file with six to eight defined keys (the primary key and five to seven 
alternate keys) should be considered as a maximum; a file with two or three 
defined keys is typical. 


11.23 XAB$I_RVB 

After an Open or Display service, the root index bucket virtual block number 
(RVB) field contains the virtual block number for the root bucket of the index 
for the key described by the XAB. 


11.24 XAB$B_SIZO through XAB$B_SIZ7 

The key size (SIZ) field defines the length of the key field within each record. 
This field contains a numeric value representing the length, in bytes, of the 
key within the record. Up to eight values can be assigned; maximum values 
depend on the type of key. This field corresponds to the FDL attribute KEY 
LENGTH or KEY SEGn_LENGTH (n is the number of the segment being 
defined). 

The XAB$B_SIZ0 through XAB$B_SIZ7 fields define the length (in bytes) of 
the key — whose starting position is defined in the key position field of the 
same XAB — within each record of an indexed file. Two types of keys can 
be defined: simple and segmented (see XAB$W_POSO through XAB$B_POS7 
field). 

When defining a simple key, the XAB$B_SIZ0 through XAB$B_SIZ7 fields 
will contain only one key size value (in XAB$B_SIZ0). 

When defining a segmented key, the XAB$B_SIZ0 through XAB$B_SIZ7 
fields must contain a key size value for each segment of the key. You should 
note that the XAB$B_SIZ0 through XAB$B_SIZ7 fields and the XAB$W_ 
POSO through XAB$B_POS7 fields must contain an equal quantity of key size 
values and key position values. VAX RMS associates the first key position 
value with the first key size value to define the location and length of the first 
segment of a segmented key, and so forth. 

When the data type of the key is string, the total size (sum of all sizes) of the 
key must be less than 256 bytes. 

When the data type of the key is 2-byte integer or 2-byte binary, XAB$B_ 
SIZO must equal 2 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain a 
value of 0. If size is 0, it is defaulted to 2. 

When the data type of the key is 4-byte integer or 4-byte binary, XAB$B_ 
SIZO must equal 4 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain a 
value of 0. If size is 0, it is defaulted to 4. 

When the data type of the key is 8-byte integer or 8-byte binary, XAB$B_ 
SIZO must equal 8 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain a 
value of 0. If size is 0, it is defaulted to 8. 

When the data type of the key is packed decimal, the size specified by 
XAB$B_SIZ0 must be from 1 through 16, and XAB$B_SIZ1 through XAB$B_ 
SIZ7 must contain a value of 0. 
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11.25 XAB$B_TKS 

After an Open or Display service, the total key size (TKS) field contains the 
total key size, that is, the sum (in bytes) of XAB$B_SIZ0 through XAB$B_ 
SIZ7, for the key described by the XAB. 
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1 2 Protection XAB (XABPRO) 


12.1 


The protection XAB (XABPRO) specifies the ownership, accessibility, and 
protection for a file. Although a XABPRO is typically used as input to the 
Create service, you can use a XABPRO to change the protection of a file when 
you execute the Close service if you have write accessibility to the file and 
have accessed the file for some type of modification (Put, Update, Delete, or 
Truncate). 


Summary of Fields 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABPRO field is presented in Table 12-1. 


Table 12-1 XABPRO Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XAB$I_ACLBUF 

4 

None 

Address of buffer that contains ACL 

XAB$I_ACLCTX 

4 

None 

ACL positioning context 

XAB$W_ACLLEN 

2 

None 

Receives the length of an ACL during 
an Open or Display service 

XAB$W_ACLSIZ 

2 

None 

Length of buffer containing binary ACEs 

X AB$L _ACLSTS 

4 

None 

System error status for ACL processing 

XABSB—BLN 1 

1 

None 

Block length 

XABSB—COD 1 

1 

None 

Type code 

XAB$W_GRP 2 

2 

FILE OWNER 

Group number of file owner 

XAB$W_MBM 2 

2 

FILE OWNER 

Member number of file owner 

X AB$B_MT ACC 

1 

FILE MT_PROTECTION 

Magnetic tape accessibility 

XAB$L_NXT 

4 

None 

Next XAB address 

XAB$W_PRO 

2 

FILE PROTECTION 

File protection; contains four separate 
fields denoting protection for system, 
owner, group, and world 

XAB$B_PROT_OPT 

1 

None 

File protection options 

XAB$L_UIC 

4 

FILE OWNER 

User identification code; contains both 
the group and member fields 


Statically initialized field (by the VAX MACRO SXABPRO macro) to identify this control block as a XABPRO. 
2 Field cannot be initialized by the VAX MACRO SXABPRO macro. 


Each XABPRO field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
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systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABPRO and $XABPRO_ 
STORE macros are defined in Appendix B. 


12.2 XAB$L _ACLBUF 

The ACL buffer field (ACLBUF) contains the address of a buffer area that 
contains an access control list (ACL) for this file. The ACL buffer contains one 
or more access control entries (ACE) in binary format; the ACL is processed 
until either reaching an ACE for which the length byte has a value of 0 or 
reaching the end of a buffer as indicated by XAB$W_ACLSIZ. The ACL buffer 
is used as input to a Create service and output from an Open or Display 
service. The address in XAB$L—ACLBUF is used only as input to these 
services. 

During a Create operation, if the XAB$L —ACLBUF field has a value other 
than 0, VAX RMS attempts to create the file using the value in the ACL 
buffer. When the XAB$L—ACLBUF field has a value of 0 during a Create 
operation, the file has an ACL only if an ACL is specified by the system-wide 
defaults. Once a file has been created, the ACL cannot be changed using VAX 
RMS. 

During an Open or a Display operation, if the XAB$L —ACLBUF field has a 
value other than 0, VAX RMS passes this address to the file system. The file 
system then fills the user's buffer with the file's ACL (in binary format). If 
the entire ACL does not fit into the user's buffer the file system puts only as 
many ACEs into the buffer as will fit. (See XAB$L_ACLCTX field for more 
information.) 

You can convert an ASCII ACL to binary format by using the SPARSE— 

ACL system service, and you can convert an ACL from binary format to 
ASCII using the $FORMAT_ACL system service. For information about 
using the SPARSE—ACL and $FORMAT_ACL services, see the VAX/VMS 
System Routines Reference Volume and the VAX/VMS System Services Reference 
Manual. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


12.3 XAB$I_ACLCTX 

The XABSL—ACLCTX field is used as a placeholder by VAX RMS, and it is 
used as an input and output field by VAX RMS during Open and Display 
operations when the XAB$L—ACLBUF field has a value other than 0. In 
order to read an ACL beginning with the first ACE, the XAB$L_ACLCTX 
field must have a value of 0. When the initial Open or Display operation is 
complete, VAX RMS fills the XAB$L —ACLCTX field with a value that serves 
as a context field, allowing subsequent Open or Display operations that read 
the remainder of the ACL (if the entire list of ACEs did not fit into the user's 
buffer). 

For example, suppose you perform an Open operation, find that the value of 
XAB$W_ACLLEN is greater than the ACL buffer, and then perform Display 
operations until all of the ACEs in the ACL have been returned. You can then 
reread the entire ACL on subsequent Opens or Displays only if you set the 
value of the XAB$L-ACLCTX field to 0. 
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The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


12.4 XAB$W_ACLLEN 

The ACL length (ACLLEN) field receives the length (in bytes) of the access 
control list for the file during an Open or a Display operation. If the file has 
no ACL, the XAB$W_ACLLEN field has a value of 0. 

If the file has an ACL that fits entirely into the user's buffer, then the 
XAB$W_ACLLEN field has a value equal to the number of valid bytes of 
information in the buffer. If the file's ACL does not fit entirely into the user's 
buffer, then the XAB$W__ACLLEN field has a value equal to the length of the 
entire ACL (not just the length of that portion that fits into the buffer). 

When the ACL cannot fit entirely in the user's buffer, there is no field that 
shows the number of valid bytes of information were actually returned. You 
can obtain this information only by processing binary ACEs until you reach 
either an ACE with a value of 0 or the end of the buffer. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


12.5 XAB$W_ACLSIZ 

The ACL buffer size (ACLSIZ) field specifies the length of the user buffer that 
contains (or will contain) binary ACEs used as input to a Create service and 
as output to an Open or Display service. 

VAX RMS passes all information, including the ACL buffer, to and from the 
file system using buffered I/O. Since the size of a buffered I/O is constrained 
by limitations imposed by user's BYTLM quota) limitations imposed by 
MAXBUF) the user's BYTLM quota and the MAXBUF sysgen parameter, 
the size of the ACL buffer is, in turn, effectively limited by these factors. 

In VAX/VMS Version 4.0, VAX RMS never uses more than 512 bytes of a 
buffered I/O, excluding the ACL buffer. Therefore, the size of the ACL buffer 
plus 512 bytes cannot exceed either the BYTLM quota for the process or the 
MAXBUF value for the system. 

The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


12.6 XAB$I_ACLSTS 

The ACL error status (ACLSTS) field contains a system error status relating 
to the processing of ACLs. A value is returned to this field upon a successful 
return from a Create, Open, or Display service. 

Whenever you use the XAB$L_ACLBUF, XAB$L_ACLCTX, XAB$W_ 
ACLLEN, or XAB$W_ACLSIZ fields, be sure to observe the following 
error-handling procedures: 

• If the FAB$L_STS field (R0) contains an error status, handle the error in 
the usual manner. 
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• If the FAB$L_STS field (RO) contains a success status, then you must 
check the value in XAB$L—ACLSTS. If XAB$L_ACLSTS contains a 
success status, then the entire operation completed successfully and no 
further action is required; if XAB$L_ACLSTS contains an error status, 
handle the error appropriately. Note that a value is placed in the XAB$L_ 
ACLSTS field only when a success status is returned in FAB$L_STS (RO). 

This extra level of error checking is necessary because the success or failure 
of reading and writing ACLs is independent of the success or failure of the 
whole operation. Thus, in the absence of this additional error checking, it 
would be possible to create a file successfully even though an ACL error had 
occurred. 

This field is relevant only when an ACL is used on a Create service or when 
an ACL is returned from an Open or Display service. The use of this field for 
DECnet remote file access is not supported, and it is ignored during DECnet 
operations. 


12.7 

XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABPRO, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic 
XAB$C_PROLEN (this is done by the VAX MACRO $XABPRO macro). 

12.8 

XAB$B_COD 

The type code (COD) field is a static field that identifies this control block 
as an XABPRO. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_PRO (this is done by the VAX MACRO $XABPRO macro). 

12.9 

XAB$W_GRP 

The file owner group number (GRP) field contains the half of the XAB$L_ 
UIC field that defines the group number. Refer to the XAB$L_UIC field 
description for additional information. This field corresponds to the FDL 
attribute FILE OWNER. 



When using the VAX MACRO $XABPRO macro, this field cannot be 
initialized directly, although initializing the XAB$L_UIC field will set the 
corresponding value in this field. 

12.10 

XAB$W_MBM 



The file owner member number (MBM) field contains the half of the XAB$L — 
UIC field that defines the member number. Refer to the XAB$L_UIC field 
description for additional information. This field corresponds to the FDL 
attribute FILE OWNER. 

When using the VAX MACRO $XABPRO macro, this field cannot be 
initialized directly, although initializing the XAB$L—UIC field will set the 
corresponding value in this field. 
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12.11 XAB$B_MT ACC 

The magnetic tape accessibility (MTACC) field enables you to access HDR1 
labels for ANSI-labeled magnetic tapes, in compliance with ANSI standards. 
The value specified in the XAB$B_MTACC field is input to the Create service 
and output from the Open and Display services for magnetic tape only. This 
field corresponds to the FDL attribute FILE MT_PROTECTION. 

The character to be inserted in the accessibility field of the HDR1 label must 
be one of the following: 

• An uppercase letter from A through Z 

• A digit 0 through 

• One of the following special characters: (SPACE) !%&'()* + ,-. / : ; 

< = > ? 

Note that if this field is not specified or if the specification is invalid, a space 
character will be inserted into the HDR1 accessibility field. 

This field is not supported for DECnet operations; it is ignored. 


12.12 XAB$I_NXT 


The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 


12.13 XAB$W_PRO 


The file protection (PRO) field specifies the file access privilege to be assigned 
to the four classes of users: system, owner, group, and world. This field 
corresponds to the FDL attribute FILE PROTECTION. 

This field consists of four 4-bit subfields; each subfield is a binary options field 
where each possible file access privilege has a corresponding bit assignment. 
The file access privileges must be specified in the following order: 

< SYSTEM,OWNER,GROUP, WORLD > 

To deny access, the bit values in the protection word are set to 1. Thus, 
specifying a particular access right code clears the bit to 0. 

The following list associates each subfield with its symbolic offset: 

• System—XAB$V_SYS 

• Owner—XAB$V_OWN 

• Group—XAB$V_GRP 

• World—XAB$V_WLD 

Additionally, each access specification has the following mask values: 

• No read access—XAB$M_NOREAD 

• No write access—XAB$M_NOWRITE 

• No execute access—XAB$M_NOEXE 
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• No delete access—XAB$M__NODEL 

A user is granted the maximum number of types of access rights for each of 
the classes to which he belongs. 

Each access code consists of 4 bits for each user class, or 4 subfields in 
the word identified by XAB$W_PRO. This field is organized as shown in 
Figure 12-1. 

Figure 12-1 File Protection Field 
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If you do not explicitly specify file protection when you invoke the Create 
service, VAX RMS attempts to determine file protection in the following order: 

1 Using the protection assigned to an existing file of the same name 

2 Using the default file protection of the directory 

3 Using the process-default protection 

The following chart provides detailed descriptions of the four user classes: 


User Class 

Description 

System 

Specifies access rights for users executing under a system 
UIC, that is, users whose group number is less than the value 
for a system UIC, which is defined by the system manager 
(usually 10 or less). 

Owner 

Specifies access rights for the owner of the file. A user is 
considered the owner of the file only if both the group and 
member number fields of the accessing process match the 
group and member number fields of the file owner's UIC 
stored with the file. 

Group 

Specifies the access rights for users whose group number 
matches the group number field of the file owner. 

World 

Specifies the access rights for any user. It is normally 
allowed for users not within the system, owner, or group 
classifications. 


12.14 XAB$B_PROT_OPT 

The ACL file protection (PROT_OPT) field has only a single bit defined, 
the XAB$V_PROPAGATE bit, which is used as input during an Enter or 
a Rename operation. (During a Rename operation, the protection XAB is 
assumed to be attached to FAB #2.) This field has no corresponding FDL 
attribute. 
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The XAB$B_PROT_OPT field is a binary options field where each file 
protection option has a corresponding bit assignment. Options are identified 
using mnemonics, and each option has its own symbolic bit offset and mask 
value. For example, the PROPAGATE option has a symbolic bit offset of 
XAB$V_PROPAGATE and a mask value of XAB$M_PROPAGATE. 

If the XAB$V_PROPAGATE bit is set in this field during either an Enter or 
Rename operation, the file receives new security attributes when the new 
directory entry is made. These security attributes follow the same rules as 
apply during a Create operation. For example, if a lower version of a new file 
exists, the new file inherits the security attributes of the next lower version of 
the file. If the XAB$V_PROPAGATE bit is not set, the security attributes of 
the new file do not change. 

This field is not supported for DECnet operations; it is ignored. 


12.15 XAB$L_UIC 

The user identification code (UIC) field combines the two XABPRO fields that 
define the UIC of the owner of a file: the XAB$W_GRP (group number) and 
XAB$W_MBM (member number) fields. Both numbers are octal numbers. 

The valid range for a group number is 0 to 37777; the valid range for a 
member number is 0 to 177777. Note that the maximum value in each case 
(37777 and 177777) is reserved for DIGITAL use only. This field corresponds 
to the FDL attribute FILE OWNER. 

The symbolic offsets for the group number field and the member number 
field respectively are XAB$W_GRP and XAB$W_MBM. 

The total user identification field, including both the group and member 
number fields, has a symbolic offset of XAB$L_UIC. 

Note that if no file protection XAB is provided or if the user identification 
field is null for a Create service, VAX RMS determines the owner's UIC using 
the following logical order: 

1 The owner UIC of an existing version of the file if the creating process has 
ownership rights to the owner of the previous version. 

2 The owner UIC of the parent directory, if the creating process has 
ownership privileges to the owner of the parent directory. 

3 The UIC of the creating process. 

If you wish to create an output file with a UIC different than your own, you 
must have system privilege (SYSPRV). 
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1 3 Revision Date and Time XAB (XABRDT) 


The revision date and time XAB (XABRDT) specifies the revision date and 
time and the revision number when a Close service is invoked for a file. The 
XABRDT operates much like the Date and Time XAB (XABDAT) when input 
to the Create, Open, or Display services. However, when you gain access to 
a file for writing, issuing a Close service for that file causes the revision date 
and time to be set from the current date and time and the revision number 
to be incremented. Thus, any revision date and time you specify through the 
XAB on a Create service is lost. 

You can input the XABRDT to a Close service and cause the file's revision 
date and time and revision number to take on the specified values. If you 
wish to change the revision date and time when you close the file, you must 
have write access to the file and have accessed the file for some type of 
modification (Put, Update, Delete, or Truncate). 


13.1 Summary of Fields 

The two XABRDT fields that specify revision information are described below. 

• Revision date and time (XAB$Q_JRDT), which is a 64-bit binary field that 
indicates the date and time at which the file was last updated. 

• Revision number (XAB$W__RVN), which provides the number of times this 
file was opened for write operations. 

The following list describes how these two XABRDT fields are used by the 
VAX RMS file-processing services. 


Service 

XAB$Q_RDT 

XAB$W_RVN 

Close 

Input 

Input 

Create 

Input 

Input 

Display 

Output 

Output 

Erase 

Not used 

Not used 

Extend 

Not used 

Not used 

Open 

Output 

Output 


If you specify a revision date and time of 0, VAX RMS will substitute the 
current date and time when you invoke the Close service. If, however, the 
XABRDT existed on an Open (or a Display) service, the XAB$Q_RDT field 
will be filled with the existing file's revision date and time value. Because the 
XAB$Q_RDT field has been filled (and is no longer 0), VAX RMS will not 
substitute the current date and time. 

The XABRDT block should be used only in those cases in which you want to 
specify a new (and nondefault) value for the XAB$Q_RDT and XAB$W_RVN 
fields. These fields may be set any time after the Open service, but must 
be set before the Close service. If the fields are set before the Open service, 
the file's existing revision date and time and revision number will override 
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the values you specified. If you only want to examine the contents of the 
XAB$Q_RDT and XAB$W_RVN fields, you can do so by simply consulting 
the information already contained in the appropriate fields of the XABDAT 
block. 

The symbolic offset, size, FDL equivalent, and a brief description of each 
XABRDT field are presented in Table 13-1. 


Table 13-1 XABRDT Fields 


Field Offset 

Size 

(bytes) 

FDL Attribute 

Description 

XABSB-BLN 1 

1 

None 

Block length 

XABSB—COD 1 

1 

None 

Type code 

XAB$I_NXT 

4 

None 

Next XAB address 

XAB$Q_RDT 2 

8 

DATE REVISION 

Revision date and time 

XAB$W_RVN 2 

2 

FILE REVISION 

Revision number 


1 Statically initialized field (by the VAX MACRO $XABRDT macro) to identify this 
control block as a XABRDT. 


2 Field cannot be initialized by the VAX MACRO SXABRDT macro; these fields 
must be set after an Open or Create service and before the Close service to be 
used as input to the Close service. 


Each XABRDT field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX /VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the $XABRDT and $XABRDT_STORE services 
are defined in Appendix B. 


13.2 

XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABRDT, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_RDTLEN (this is done by the VAX MACRO $XABRDT macro). 

13.3 

XAB$B_COD 

The type code (COD) field is a static field that identifies this control block 
as an XABRDT. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_RDT (this is done by the VAX MACRO $XABRDT macro). 

13.4 

XAB$L_NXT 
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XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 














Revision Date and Time XAB (XABRDT) 

XAB$Q_RDT 

13.5 XAB$Q_RDT 

The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time at which the file was last updated. This field 
corresponds to the FDL attribute DATE REVISION. 

Note that this field is limited to a granularity of 1 second for remote files. 

13.6 XAB$W_RVN 

The revision number (RVN) field contains a numeric value that indicates 
the number of times this file was opened for write operations. This field 
corresponds to the FDL attribute FILE REVISION. 
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14 Summary XAB(XABSUM) 


The summary XAB (XABSUM) can be associated with a FAB at the time a 
Create, Open, or Display service is issued. The presence of this XAB during 
these calls allows VAX RMS to return to your program the total number of 
keys and allocation areas defined and the version number when the file was 
created. Note that an XABSUM is used only with indexed files. 


14.1 Summary of Fields 

The symbolic offset, size, and a brief description of each XABSUM field are 
presented in Table 14-1. 


Table 14-1 XABSUM Fields 


Field Offset 

Size 

Description 

XABSB—BLN 1 

Byte 

Block length 

XABSB—COD 1 

Byte 

Type code 

XAB$B_NOA 2 

Byte 

Number of allocation areas defined for the file 

XAB$B_NOK 2 

Byte 

Numbers of keys defined for the file 

XAB$L_NXT 

Longword 

Next XAB address 

XAB$W_PVN 2 

Word 

Prologue version number 


Statically initialized field (by VAX MACRO SXABSUM macro) to identify this 
control block as an XABSUM. 

2 Field cannot be initialized by the VAX MACRO $XABSUM macro. 


Each XABSUM field is described below. Unless indicated otherwise, each 
field is supported for DECnet operations using remote files with a VAX/VMS 
system as the remote node. Note that the words "DECnet operations" in the 
following descriptions refer to remote file operations between two VAX/VMS 
systems. See the VAX/VMS Networking Manual for information about the 
support of VAX RMS options for remote file access to non-VAX/VMS systems. 

The format and arguments of the VAX MACRO $XABSUM and $XABSUM_ 
STORE macros are defined in Appendix B. 


14.2 XAB$B_BLN 


The block length (BLN) field is a static field that defines the length of the 
XABSUM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_SUMLEN (this is done by the VAX MACRO $XABSUM macro). 
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14.3 

XAB$B_COD 

The type code (COD) field is a static field that identifies this control block 
as an XABSUM. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_SUM (this is done by the VAX MACRO $XABSUM macro). 

14.4 

XAB$B_NOA 

The number of allocation areas (NOA) field indicates the number of allocation 
areas defined when the file was created. Refer to Section 8, XAB$B__AID for 
information about multiple allocation areas. 

14.5 

XAB$B_NOK 

The number of keys (NOK) field indicates the number of keys defined when 
the file was created. Refer to Section 11 for more information. 

14.6 

XAB$L_NXT 

The next XAB address (NXT) field contains a symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 

14.7 

XAB$W_PVN 

The prologue version number (PVN) contains a numeric value that indicates 
the prologue number defined when the file was created. For more information 
about prologue numbers, refer to Section 11, XAB$B_PROLOG. 


14-2 












15 Terminal XAB (XABTRM) 


The terminal XAB (XABTRM) allows extended terminal read operations to 
occur when a VAX RMS Get service is used for a terminal device. Unlike 
other XABs, the XABTRM is associated with a RAB (record stream). The 
XABTRM provides information that VAX RMS passes to the terminal driver to 
process a user-defined item list that defines the terminal read operation. 


15.1 Summary of Fields 

The symbolic offset, size, and a brief description of each XABTRM field are 
presented in Table 15-1. 


Table 15-1 XABTRM Fields 


Field Offset 

Size 

(bytes) 

Description 

XABSB—BLN 1 

1 

Block length 

XABSB—COD 1 

1 

Type code 

XAB$L_ITMLST 

4 

Item list address 

XAB$W_ITMLST_LEN 

2 

Item list length 

XAB$L_NXT 

4 

Next XAB address 

Statically initialized field (by the VAX MACRO $XABTRM macro) to identify this 
control block as an XABTRM. 


To perform the extended terminal read operation, the following information 

is required: 

• In the RAB, the RAB$L_ROP field RAB$V_ETO option must be specified 
(set). 

• In the RAB, the RAB$L_XAB field must contain the address of the 
XABTRM. 

• In the XABTRM, the XAB$L_ITMLST and XAB$W_ITMLST_LEN fields 
must contain the starting address and length of a valid terminal driver 
read function item list. 

• The item list must be supplied according to the conventions described for 
creating an item list for the terminal driver in the VAX/VMS I/O User's 
Reference Manual: Part 1 in the VAX/VMS I/O Reference Volume. 

An item list consists of one or more item list entries, where each item 
list entry defines an attribute of the terminal read operation. Instead 
of defining terminal read arguments in the RAB, all such arguments 
(including certain arguments available only using the item list method) 
are defined in the item list. The following list shows the RAB$L_ROP 
options related to a terminal read operation and the equivalent item list 
codes: 
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15.3 


15.4 

15.5 


Terminal XAB (XABTRM) 

Summary of Fields 


RAB$I_ROP 

Bit Offset 

Item List Code 

RAB$V CVT 

TRM$_MODIFIERS, bit TRM$M_TM_CVTLOW 

RAB$V_PMT 

TRM$_PROMPT 

RAB$V_PTA 

TRM$_MODIFIERS, bit TRM$M_TM_PURGE 

RAB$V_RNE 

TRM$_MODIFIERS, bit TRM$M_TM_NOECHO 

RAB$V_RNF 

TRM$_MODIFIERS, bit TRM$M_TM_NOFILTR 

RAB$V_TMO 

TRM$TIMEOUT 


Each item list code required for the terminal read operation would be 
placed in an item list entry along with other information required for 
the item list. Each item list entry is always three longwords in length. 
Note that VAX RMS does not validate the item list. If the item list is 
invalid, VAX RMS returns a status of RMS$_QIO in the RAB$L_STS field 
and the specific terminal driver QIO status in the RAB$L_STV field (see 
the VAX/VMS I/O User's Reference Manual: Part I in the VAX/VMS I/O 
Reference Volume). 

Each XABTRM field is described below. Use of the XABTRM is not supported 
for DECnet operations between two VAX/VMS systems. Thus, access to 
XABTRM fields for DECnet operations is not supported. There are no 
equivalent FDL attributes for the XABTRM fields. 

The format and arguments of the VAX MACRO $XABTRM and $XABTRM_ 
STORE macros are defined in Appendix B. 


XAB$B_BLN 

The block length (BLN) field is a static field that defines the length of the 
XABTRM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_TRMLEN (this is done by the VAX MACRO $XABTRM macro). 

XAB$B_COD 

The type code (COD) field is a static field that identifies this control block 
as an XABTRM. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_TRM (this is done by the VAX MACRO $XABTRM macro). 

X AB$I_ITM LST 

The item list address (ITMLST) field contains a symbolic address of the item 
list that defines the extended terminal read operation. 


XAB$W_ITMLST_LEIU 


The item list length (ITMLST_LEN) field contains a numeric value that 
indicates the length of the item list, in bytes. 
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Terminal XAB (XABTRM) 

XAB$I_NXT 


15.6 XAB$I_NXT 

The next XAB address (NXT) field contains a symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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PART III VAX RMS Services 


Part III lists the format of each VAX RMS service and describes 
each service in detail. Each VAX RMS service is documented in 
a structured format called the routine template. See Introduction 
to VAX/VMS System Routines for a discussion of the template 
structure and how it is used. 

Note that the calling format for each service requires a place holder 
(a comma) if you omit the first optional argument (err) but include 
the second optional argument (sue). 










VAX RMS Services 

$CLOSE 


$CLOSE 

The Close service terminates file processing and closes the file. 

This service performs an implicit Disconnect service for all record 
streams associated with the file. 

FORMAT 

SYSSCLOSE fab [ f [err] [ f sue]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in R0 is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Close service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Close service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 


DESCRIPTION You can invoke the Close service only when no operation is currently under 

way (by your process) for the file being processed; that is, when no VAX RMS 
requests for the file are outstanding. When this condition is satisfied, the file 
can be closed, which sets the internal file identifier field to 0. 
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$CLOSE 


When the Close service is invoked properly, VAX RMS disconnects all RABs 
for you, performs the various cleanup procedures (including file option 
processing and XAB processing), and closes the file. The only types of XABs 
that the Close service processes are the file protection XAB (XABPRO) and 
revision date and time XAB (XABRDT). It will process these XABs only if the 
file was opened or created for write access. 

If a process tries to implement the truncate service when closing a sequential 
file, it must have sole write access to the file. If other processes have write 
access to the file, it remains accessible until all processes have completed. 

If other processes have the file open for read access , VAX RMS defers the 
truncation until the final process having read access closes the file. 

Table RMS-1 lists the control block fields read as input by the Close service. 
Note that if the FAB$V_DLT, FAB$V_SCF, or the FAB$V_SPL bits are set 
by the associated Open or Create service, VAX RMS does not act on them 
for the Close service. For example, if you open the file and specify that it 
be deleted on close by setting the FAB$V_DLT bit, the file will be deleted 
by VAX RMS when it is closed irrespective of the bit's state when the Close 
service is invoked. 

For additional information on the fields accessed by this service, see Part II. 


Table RMS-1 Close FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

FABSW-JFI 1 


Internal file identifier. 

FAB$L_FOP 


File-processing options. 


FAB$V_DLT 

Delete on close. 


FAB$V_RWC 

Rewind magnetic tape volume. 


FAB$V_SCF 2 

Submit file as batch job (sequential files only). 


FAB$V_SPL 2 

Submit to print queue (sequential files only). 


FAB$V_TEF 

Truncate at end of file (sequential files only). 

FABSI_XAB 


Next XAB address. 


XABPRO 

Modify file protection and ownership. 


XABRDT 

Modify revision date and number. 

Required input to FAB 


2 Not supported for DECnet operations 


Table RMS-2 lists the control block fields written as output by the Close 
service. 
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SCLOSE 


Table RMS-2 Close FAB and XAB Output Fields 


Field Name 

Option or 
XAB Type 

Description 

FAB$W_IFI 


Internal file identifier (cleared). 

FAB$L_STS 


Completion status (also returned in Register 0). 

FAB$I_STV 


Status value. 

FABSI_XAB 


Next XAB address. 


XABRDT 

New revision date and number are returned. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMS$_COD 

RMS$_DNR 

RMS$_IMX 

RMS$_NORMAL 

RMS$_SUC 

RMS$_WBE 

RMS$_XAB 


RMS$_ATR 

RMS$_BUSY 

RMS$_CRC 

RMS$_EXENQLM 

RMS$_MKD 

RMS$_PRV 

RMS$_SUP 

RMS$_WER 


RMS$_ATW 

RMS$_CCF 

RMS$_DAC 

RMS$_FAB 

RMSS—NET 

RMS$_SPL 

RMS$_SUPPORT 

RMS$_WLK 


RMS$_BLN 

RMS$_CDA 

RMS$_DME 

RMS$_IFI 

RMS$_NETFAIL 

RMS$_STR 

RMS$_SYS 

RMS$_WPL 


Note that even though a failure may be indicated by the completion status 
code value, the file was nonetheless closed, provided that the internal file 
identifier value (FAB$W_IFI) was cleared by VAX RMS. 
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$CONNECT 



The Connect service establishes a record stream by associating and 
connecting a RAB with a FAB. You can invoke the Connect service 
only for files that are already open. 

FORMAT 

SYSSCONNECT rab[,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L__STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Connect service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Connect service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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$CONNECT 


DESCRIPTION Any number of RABs can be connected to a FAB if the multistream (FAB$V_ 

MSE) option was set in the file-sharing field (FAB$B_SHR) when the file was 
opened or created. Each RAB represents an independent record stream. 

When you issue a Connect service, VAX RMS allocates an internal counterpart 
for the RAB. This counterpart consists of the internal controls needed to 
support the stream, such as record pointers and request status information. 

All required I/O buffers are also allocated at this time. 

The Connect service also initializes the next record pointer to the first record. 
In indexed files, the key of reference establishes the index of the next record 
pointer. 

If you set the end-of-file (RAB$V_EOF) option in the RAB$L_ROP field 
when issuing a Connect service, VAX RMS will examine the organization of 
the file being processed to determine the end-of-file positioning strategy. 

For sequential files, VAX RMS will automatically position to the end of the 
file. If the file has been opened for shared access, the next-record position is 
maintained at the current end-of-file position for successive $PUT operations. 
With successive $PUT operations, potentially by the different processes 
accessing the file, records are placed in the file in the order of the $PUT 
operations. 

For example, assume that processes A and B are sharing a sequential file and 
each process is putting data into the file. Process A puts a record at the end 
of the file and intends to put another record at the new end-of-file location. 
However, before process A can put the next record in the file, process B 
gains access to the file and puts a record at the end of the file. In order to 
ensure that the next record from process A does not overwrite the record 
just inserted by proceess B, VAX RMS updates process A's write pointer to 
the new end-of-file position. That is, the location immediately following the 
location of process B's record. 

For relative files, VAX RMS will actually position to the next record beyond 
the last currently existing record in the file. (Any record that is inserted will 
be at the end of the file, and any sequential access record requested will 
return an RMS$_EOF status.) 

For indexed files, VAX RMS will verify that the first record inserted is inserted 
in the proper sort order. If the record cannot be inserted in the proper sort 
order due to explicit user action, VAX RMS will return a sequence error: 
RMS$_SEQ. 

Get services that specify the sequential record access mode (RAB$B_RAC is 
RAB$C_SEQ) will return an RMS$_EOF status. Get services that specify the 
random access mode (RAB$B_RAC is RAB$C_KEY), will ignore (turn off) the 
end-of-file positioning. Positioning to end-of-file is supported for all indexed 
files, regardless of how many indexes the file contains. However, the EOF 
positioning is supported only when accessing a file by the primary key. If the 
specified key of reference is a secondary key, then an RMS$_ROP message 
will be returned. 

In most cases, setting the RAB$V_EOF bit will be sufficient to guarantee that 
a record to be inserted in a particular file will be put at the logical end of the 
file. However, if a relative file or an indexed file is shared by two or more 
active processes, the following could occur. 
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Assume that process A has invoked the Connect service after setting the 
RAB$V_EOF bit and is positioned to the end of the file. Before process A can 
do a $PUT, process B inserts a record into the file and changes the current 
record position. When process A attempts to do a $PUT into the position 
that was formerly the end of the file, the record may be inserted improperly. 
It may be inserted either before or after the record inserted by process B, 
depending on the respective key values. Or, the $PUT operation may even 
fail if the keys have the same value and duplicates are not allowed. 

Table RMS-3 lists the control block fields read as input by the Connect 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-3 Connect RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RAB$I_FAB 1 


File access block address (required to access 
the internal file identifier field, FAB$W_IFI). 

RABSW-ISI 1 


Internal stream identifier (must be 0). 

RAB$B_KRF 


Key of reference (applies only to indexed 
files). 

RAB$B_MBC 2 


Multiblock count (applies only to sequential 
files residing on disk devices). 

RAB$B_MBF 2 


Multibuffer count. 

RAB$I_ROP 


Record-processing options: 


RAB$V_ASY 

Asynchronous: performs Connect service 
asynchronously. 


RAB$V_BIO 

Block I/O: specifies that only block I/O 
operations are permitted. The FAB$B_FAC 
field FAB$V_BRO or FAB$V_BIO option must 
be specified on the Open or Create service. 


RAB$V_EOF 3 

End-of-file: positions to the end of the file 
upon execution of the Connect service. 


RAB$V_RAH 2 

Read ahead: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 


RAB$V_ 

WBH 2 

Write behind: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 

1 Required input to the Connect service 

2 Not supported for DECnet operations 

3 Refer to text for exceptions. 



Table RMS-4 lists the control block fields written as output by the Connect 
service. 
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Table RMS-4 

Connect RAB Output Fields 

Field 


Name 

Description 

RAB$W_ISI 

Internal stream identifier. 

RAB$L_STS 

Completion status code (also returned in Register 0). 

RAB$I_STV 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_CDA 

RMS$_GBC 

RMS$_KRF 

RMS$_NORMAL 

RMS$_ROP 

RMS$_SUP 


RMS$_BLN 

RMS$_CRMP 

RMS$_IAL 

RMS$_MBC 

RMS$_PENDING 

RMSS—RPL 

RMS$_SUPPORT 


RMS$_BUG_DAP 

RMS$_DME 

RMS$_IFA 

RMS$_NET 

RMS$_RAB 

RMS$_STR 


RMS$_CCR 

RMSS—FAB 

RMS$_IFI 

RMSS—NETFAIL 

RMS$_RFM 

RMS$_SUC 
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$CREATE 

The Create service constructs a new file according to the attributes 
you specify in the FAB. If any XABs are chained to the FAB, then the 
characteristics described in the XABs are applied to the file. This 
service performs implicit Open and Display services. 

FORMAT 

SYSSCREATE fab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Create service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Create service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION The Create service first uses the information from the specified FAB. If an 

allocation control XAB is present, however, its allocation quantity (XAB$L_ 
ALQ), allocation options (XAB$B_AOP, only for the XAB$V_CTG and 
XAB$V_CBT options), bucket size (XAB$B_BKZ), and default extension 
quantity (XAB$W_DEQ) fields are used instead of the corresponding fields 
of the FAB. When either key definition or allocation XABs are present, they 
can be grouped in any order. If a name block (NAM) is also connected to the 
FAB, VAX RMS fills in its fields with information about the created file. The 
Create service leaves the file opened. 

When a search list logical name is used, the file is placed in the first resulting 
search list file specification, except if the create-if (FAB$L_FOP field FAB$V_ 
CIF) option is specified. If the FAB$L_FOP field FAB$V_CIF option is set, 
all possible search list file specifications are searched to locate the file. If the 
file is found when the create-if option was set, the existing file is opened 
(not created); if the file is not found, VAX RMS creates the file using the first 
resulting search list file specification. 

The Create service implies write access, which is the default. You need not 
specify the file access (FAB$B_FAC) field FAB$V_PUT option when invoking 
a Create service in your program. 

Table RMS-5 lists the control block fields read as input by the Create service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-5 Create FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_ALQ 


Allocation quantity; ignored if an 
allocation XAB is present. 

FAB$B_BKS 


Bucket size; ignored if an allocation XAB 
is present. 

FAB$W_BLS 


Block size (applies to magnetic tape 
only). 

FAB$W_DEQ 


Default file extension quantity; ignored if 
an allocation XAB is present. 

FABSl_DNA 


Default file specification string address. 

FAB$B_DNS 


Default file specification string size. 

FAB$B_FAC 


File access. 


FAB$V_BIO 

Block I/O access to file. 


FAB$V_BRO 

Block or record I/O access to file. 


FAB$V_DEL 

Delete access to file. 


FABSV—GET 1 

Read access to file. 


FABSV—PUT 1 

Write access to file and explicit file 
extension. 


FAB$V_TRN 

Truncate access to file. 


FAB$V_UPD 

Update access to file and explicit file 
extension. 


1 These are the default values supplied by VAX RMS. 
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Table RMS-5 (Cont.) Create FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_FNA 2 


File specification string address. 

FAB$B_FNS 2 


File specification string size. 

FAB$L_FOP 


File-processing options. 


FAB$V_CBT 

Contiguous best try: indicates that the 
file is to be allocated contiguously on 
a "best effort" basis. If VAX RMS is 
unable to allocate the file within three 
extents, this bit is switched off by the 
Create service. To specify a single 
extent, use the FAB$V_CTG option. 


FAB$V_CIF 

Create-if: opens a file if it already exists 
or creates a file if it does not already 
exist. 


FAB$V_CTG 

Contiguous: indicates that the space for 
a file is to be allocated contiguously. 


FAB$V_DFW 3 

Deferred write: writing back to the file 
from the modified buffer is deferred. 
Applies to relative and indexed files 
and sequential files opened for shared 
access. 


FAB$V_DLT 

Delete: indicates that the file is to be 
deleted when closed. 


FAB$V_MXV 

Maximize version: indicates that the 
created file be given the specific version 
number requested or a version number 
that is one greater than the highest 
version number of an existing file. 


FAB$V_NAM 3 

Name block inputs: indicates that the 
NAM$W_DID and NAM$T_DVI fields 
in the specified NAM block are used as 
input. 


FAB$V_NFS 3 

Non-file-structured: indicates that the 
accessed volume is to be processed in a 
non-file-structured manner. 


FAB$V_OFP 

Output file parse: specifies that the 
resultant file specification string of the 
related file, if used, is to provide file 
name and file type defaults only. 


FAB$V_POS 

Current position (applies to magnetic 
tapes only). 


FAB$V_RCK 

Read-check: indicates that transfers 
from disk are to be followed by a 
read-compare operation. 


2 These fields must be specified by the user (unless the FAB$L_FOP field FAB$V_ 
TMD or the FAB$V_TMP option is set). 

3 Not supported for DECnet operations 
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Table RMS-5 (Cont.) Create FAB and XAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 


FAB$V_RWC 

Rewind on close (applies to magnetic 
tape only). 


FAB$V_RWO 

Rewind on open (applies to magnetic 
tape only). 


FAB$V_SCF 

Submit command file: indicates that 
the file is to be submitted as a batch- 
command file to the process default 
batch queue (SYSSBATCH) when the file 
is closed (applies to sequential files only). 


FAB$V_SPL 

Spool: indicates that the file is to be 
spooled to the process default print 
queue (SYS$PRINT) when the file is 
closed (applies to sequential files only). 


FAB$V_SQO 

Sequential only: indicates that the file 
can be processed in a sequential manner 
only, usually to enable DECnet-VAX file 
transfer. 


FAB$V_SUP 

Supersede: allows an existing file to be 
superseded by a new file of the same 
name, type, and version. 


FAB$V_TEF 

Truncate at end of file: indicates that 
the unused space allocated to a file will 
be deallocated when that file is closed 
(applies to sequential files only). 


FAB$V_TMD 

Temporary marked for delete: indicates 
that a temporary file is to be created, 
and then deleted when the file is closed. 


FAB$V_TMP 

Temporary: indicates that a temporary 
file is to be created and retained, but no 
directory entry will be made for this file. 


FAB$V_UF0 3 

User file open: indicates that the file will 
be created or opened only (no further 
processing of that file by VAX RMS is 
allowed). 


FAB$V_WCK 

Write-check: indicates that transfers 
to disk are to be followed by a read- 
compare operation. 

FAB$B_FSZ 


Fixed control area size. 

FABSW—GBC 3 


Global buffer count for shared files. 

FAB$W_IFI 


Internal file identifier (must be 0). 

FAB$I_MRN 


Maximum record number (applies to 
relative files and sequential files having 
fixed-length 512-byte records). 

FAB$W_MRS 


Maximum record size. 

FAB$I_NAM 


Name block address. 


3 Not supported for DECnet operations 
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Table RMS—5 (Cont.) Create FAB and XAB Input Fields 

Option or 

Field Name XAB Type Description 


File organization: indicates type of file 
organization (FABSC—SEQ 1 , FAB$C_REL, 
FAB$C_IDX). 


FAB$B_ORG 

FAB$B_RAT 

FAB$B_RFM 


FAB$B_RTV 3 

FAB$B_SHR 

FAB$V_SHRDEL 

FAB$V_SHRGET 


FAB$V_MSE 3 

FAB$V_NIL 

FAB$V_SHRPUT 

FAB$V_SHRUPD 

FAB$V_UPI 

FAB$L_XAB 

XABALL 

XABDAT 

XABKEY 

XABPRO 

XABRDT 

XABSUM 


Record attributes. 

Record format: indicates type of record 
format (FAB$C_FIX, FAB$C_VAR, 
FAB$C_VFC, FAB$C_STM, 
FAB$C_STMLF, FAB$C_STMCR, 
FABSC—UDF 1 ). 

Retrieval window size. 

File sharing. 

Allows other users to delete records 
from the file. 

Allows other users to read the file; also 
used with the FAB$V_MSE and FAB$V_ 
GET bits to specify a read-only global 
buffer cache when global buffering is 
enabled. 

Allows multistream access. 

Prohibits any type of file sharing by other 
users. 

Allows other users to write records to 
the file and extend it. 

Allows other users to update records in 
the file and extend it. 

Allows one or more users write-access 
to a shared file open for block I/O 
(applies to sequential files only). 

Extended attribute block address. 
Allocation XAB; see Section 8. 

Date and time XAB; see Section 9. 

Key definition XAB; see Section 11. 
Protection XAB; see Section 12. 

Revision date and time XAB; 
see Section 13. 

Summary XAB; see Section 14. 


1 These are the default values supplied by VAX RMS. 
3 Not supported for DECnet operations 


Table RMS-6 lists the control block fields written as output by the Create 
service. 
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Table RMS-6 Create FAB and XAB Output Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$L_ALQ 


Allocation quantity: contains actual number 
of blocks allocated. 

FAB$B_BKS 


Bucket size: applies only to relative and 
indexed files. When multiple areas are 
defined for an indexed file, the largest 
bucket size is returned. 

FABSW—BLS 


Device block size (applies to files of 
sequential organization only). 

FAB$W_DEQ 


Default file extension quantity. 

FAB$L_DEV 


Device characteristics. 

FAB$B_FAC 


File access. 

FAB$I_FOP 

FAB$V_CBT 

File-processing option. If the FAB$V_CBT 
bit is set on input, indicates whether the 
file was allocated within 3 extents (FAB$V_ 
CBT bit remains on) or more than 3 extents 
(FAB$V_CBT bit is set off). 

FAB$B_FSZ 


Fixed control area size. 

FAB$W_GBC 


Global buffer count. 

FAB$W_IFI 


Internal file identifier. 

FAB$L_MRN 


Maximum record number. 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes. 

FAB$B_RFM 


Record format. 

FABSl_SDC 


Secondary device characteristics. 

FAB$B_SHR 


File sharing. 

FAB$I_STS 


Completion status code (also returned in 
Register 0). 

FABSL_STV 


Status value: contains the I/O channel 
number if the operation is successful. 

FABSl_XAB 


Next XAB field. 


XABALL 

Allocation XAB; see Section 8. 


XABDAT 

Date and time XAB; see Section 9. 


XABFHC 

File header characteristics XAB; 
see Section 10. 


XABKEY 

Key definition XAB; see Section 11. 


XABPRO 

Protection XAB; see Section 12. 


XABRDT 

Revision date and time XAB; 
see Section 13. 


XABSUM 

Summary XAB; see Section 14. 
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Use of the NAM Block for Creating Files 

Tables RMS-7 and RMS-8 list the NAM block fields that VAX RMS uses as 
input and output for the Create service (provided that the name block address 
field (FAB$L_NAM) is specified). 


Table RMS-7 Create NAM Block Input Fields 


Field Name 

Option 

Description. 

NAM$W_ 

DID 1 


Directory identification (input only if 
the FAB$L_FOP FAB$V_NAM option 
is set). 

NAMSTJDVI 1 


Device identification (input only if the 

FAB$I_FOP FAB$V_NAM option is 

set). 

NAM$I_ESA 


Expanded string area address. 

NAM$B_ESS 


Expanded string area size. 

NAM$B_NOP 


NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word "password"). 


NAM$V_NOCONCEAL 

Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by the 
actual physical device name in the 
resultant string. 

NAMSI_RLF 


Related file NAM block address. 


NAM$L_RSA 

Related file NAM block resultant string 
address. 


NAM$B_RSL 

Related file NAM block resultant string 
length. 


NAM$I_FNB 

Related file NAM block filename status 
bits. 

NAM$I_RSA 


Resultant string area address. 

NAM$B_RSS 


Resultant string area size. 


^ot supported for DECnet operations. 


Table RMS-8 

Create NAM Block Output Fields 

Field Name 

Description 

NAM$W_ 

DID 1 

Directory identification. 

NAMST—DVI 1 

Device identification. 


1 Not supported for DECnet operations. 
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Table RMS-8 (Cont.) Create NAM Block Output Fields 


Field Name 

Description 

NAM$B_ESL 

Expanded string length (if both the NAM$L_ESA and NAM$B_ 
ESS are nonzero, and if the FAB$L_FOP FAB$V_NAM option is 
clear or if the NAM$W_DID field was 0 on input, the expanded 
file specification string is copied to the buffer specified by the 
input NAM$L_ESA field). 

NAMSW-FID 1 

File identification. 

NAM$L_FNB 

File name status bits (NAM$L_FNB is output only if NAM bit 

in FAB$I_FOP field is clear, or if NAM$W_DID field was 0 on 

input). 

NAM$B_RSL 

Resultant string length (if NAM$L_RSA and NAM$B_RSS are 
both nonzero on input, the resultant file specification is copied 
to the buffer specified by NAM$L_RSA). 

^ot supported for DECnet operations. 


Creating Files with the Create-lf Option 

The user should note that setting the create-if (FAB$V_CIF) option in the 
FAB$L_FOP field specifies simply that if a file to be processed has the same 
file specification as an existing file, then the existing file will be opened 
and no new file will be created. Some fields in the FAB, such as the file 
organization (FAB$B_ORG) and record format (FAB$B_RFM) fields, are input 
to a Create service, but are output from an Open service. For example, the 
indexed file organization could be specified in the FAB$B_ORG field on a 
create-if operation. However, if an existing sequential file has the same file 
specification as the indexed file that the user is attempting to create, then 
the existing file will be opened and the FAB$B_ORG field will be set to 
sequential. 

Creating Indexed Files 

An indexed file consists of a prologue, with which it begins, and one or more 
index structures. VAX RMS supplies the prologue with certain information 
about the file, including file attributes. 

VAX RMS supports two prologue levels, called Prolog 2 and Prolog 3. Unlike 
Prolog 2 files, Prolog 3 files allow for file compression and additional key 
types. For compatibility with RMS-11 data files that will be transported 
or copied (without conversion) between systems, you may want to choose 
Prolog 2. 

If you want to create a Prolog 3 file, you must be sure that records in the file 
are not larger than 32,224 bytes and, if the primary key is segmented, that the 
segments of the primary key do not overlap (1 or more bytes of the record 
are used in more than one segment). If the primary key contains overlapping 
segments, you can consider using that key as an alternate key instead of 
a primary key or you can request (or let VAX RMS assign you) a Prolog 2 
indexed file. 

Prolog 3 is the default prologue for VAX RMS, although VAX RMS will create 
a Prolog 2 file if the key characteristics are not compatible with Prolog 3 files. 
You can, however, override this default by requesting a specific prologue 
version. The option that you choose in requesting a specific prologue level 
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will have an effect on the behavior of VAX RMS with regard to both file 
creation and the return of error messages. 

If you explicitly request a prologue version using the XABKEY XAB$B_ 
PROLOG field in a user program, and if other file characteristics are 
incompatible with that prologue, then VAX RMS will return an error message 
and will not attempt to create the file. For example, if you explicitly specify 
Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is 
available only with Prolog 3 (such as an 8-byte integer key type), an error is 
returned and the file is not created. 

However, if a specific prologue version is not explicitly requested in the 
XAB$B_JPROLOG field, VAX RMS selects the greatest prologue level that 
can support the specified key characteristics and does not return an error 
completion code. 

In summary, there are two ways in which you can specify a particular 
prologue version: 

• Specify the XAB$B_PROLOG field in an XABKEY block in a user program, 
which affects only the file being created. 

• Use the DCL command SET RMS—DEFAULT/PROLOG to change the 
process default. 

If you do not specify the XAB$B_PROLOG field in your application program, 
VAX RMS will first examine your process defaults to check for prologue 
information. If this information is not specified in your process defaults, VAX 
RMS will then examine the system defaults. If no prologue information is 
specified at the system level, VAX RMS will attempt to create a Prolog 3 file. 

You need not be concerned with the distinctions between Prolog 2 and Prolog 
1 files. If you wish to create an indexed file with a prologue version other 
than Prolog 3, you should always specify a Prolog 2 file. If all keys in the file 
are string keys, VAX RMS provides a default of Prolog 1; in all other cases, 
Prolog 2 is the default. If the file contains all string keys and Prolog 2 is 
requested, VAX RMS attempts to create a Prolog 1 file. However, VAX RMS 
will create a Prolog 1 file only if no binary keys are present. 

Note that RMS-11 and previous versions of VAX RMS will return error 
messages if requested to process Prolog 3 files. 

If a failure is indicated, the file may indeed have been created, but will not be 
opened for processing, depending on the nature of the failure. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMSS—ACS 

RMS$_ALN 

RMSS—ATR 

RMS$_BKZ 


RMS$_ACT 

RMS$_ALQ 

RMS$_ATW 

RMS$_BLN 


RMS$_AID 

RMS$_AOP 

RMS$_BKS 

RMS$_BUG 

RMS$_CDA 

RMS$_CRE 

RMS$_CRMP 


RMS$_BUG_DAP 

RMS$_CHN 

RMS$_CREATED 


RMS$_BUG_DDI 

RMS$_COD 

RMS$_CRE_STM 
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RMSS—DAN 

RMS$_DIR 

RMSS—DNF 

RMS$_DVI 

RMS$_ESA 

RMS$_EXP 

RMS$_FLG 

RMS$_FNF 

RMS$_FSZ 

RMS$_IAL 

RMS$_IFA 

RMS$_IMX 

RMS$_KSI 

RMS$_MRN 

RMS$_NET 

RMS$_NORMAL 

RMSS—POS 

RMS$_RAT 

RMS$_RLF 

RMS$_RST 

RMS$_SHR 

RMS$_SUC 

RMS$_SUPPORT 

RMS$_UPI 

RMS$_WPL 


RMS$_DEV 

RMS$_DME 

RMSS—DNR 

RMS$_ENQ 

RMS$_ESS 

RMS$_FAB 

RMS$_FLK 

RMS$_FNM 

RMS$_FUL 

RMS$_IAN 

RMS$_IFI 

RMS$_IOP 

RMS$_LAN 

RMS$_MRS 

RMS$_NETFAIL 

RMSS—NPK 

RMS$_PRV 

RMS$_REF 

RMS$_RPL 

RMS$_RUNDOWN 

RMS$_SIZ 

RMS$_SUP 

RMS$_SYN 

RMS$_VER 

RMS$_XAB 


RMS$_DFL 

RMS$_DNA 

RMS$_DTP 

RMS$_ENV 

RMS$_EXENQLM 

RMS$_FEX 

RMS$_FNA 

RMSS—FOP 

RMS$_GBC 

RMS$_IBK 

RMS$_IFL 

RMS$_KNM 

RMS$_LNE 

RMS$_NAM 

RMS$_NOD 

RMS$_ORG 

RMS$_QUO 

RMS$_RFM 

RMS$_RSS 

RMS$_SEG 

RMS$_STR 

RMS$_SUPERSEDE 

RMS$_SYS 

RMS$_WLK 
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$DELETE 

The Delete service removes an existing record from a relative 
or indexed file. You cannot use this service when processing 
sequential files. 

FORMAT 

SYSSDELETE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Delete service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Delete service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION a Delete service always applies to the current record. Therefore, immediately 

before invoking the Delete service, you must establish the current record by 
issuing a Find or Get service. 

Table RMS-9 lists the control block fields read as input by the Delete service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-9 

Delete RAB Input Fields 

Field Name 

Option 

Description 

RAB$W_ISI 

RAB$I_ROP 

RAB$V_ASY 

RAB$V_FDL 

Internal stream identifier (required). 

Record-processing options. 

Asynchronous: performs Delete service 
asynchronously. 

Fast delete (applies to indexed files). 

Table RMS-10 lists the control block fields written as output by the Delete 



service. 


Table RMS-10 Delete RAB Output Fields 


Field Name 

Description 

RAB$I_STS 

RAB$I_STV 

Completion status code (also returned in Register 0). 

Status value. 



CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_CDA 

RMS$_DNR 

RMS$_IBF 

RMSS—NET 

RMS$_RAB 

RMS$_RSA 

RMS$_SUPPORT 


RMS$_BLN 

RMS$_CHK 

RMS$_FAC 

RMS$_IOP 

RMS$_NETFAIL 

RMS$_RNL 

RMS$_STR 

RMS$_SYS 


RMS$_BUG 

RMS$_CUR 

RMS$_FTM 

RMS$_IRC 

RMS$_NORMAL 

RMS$_RPL 

RMS$_SUC 

RMS$_TRE 


RMS$_BUG_DAP 

RMS$_DME 

RMS$_IAL 

RMS$_ISI 

RMS$_PENDING 

RMS$_RRV 

RMS$_SUP 

RMS$_WLK 
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$DISCONNECT 



The Disconnect service breaks the connection between a RAB and 
a FAB, thereby terminating a record stream. All system resources, 
such as I/O buffers and data structure space, are deallocated. 

FORMAT 

SYSSDISCONNECT rab[,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for the 
Disconnect service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Disconnect service invokes 
if the operation is successful. The sue argument is the address of the entry 
mask of this user-written completion routine. 
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DESCRIPTION The Close service (see $CLOSE) performs an implied disconnect for all 

record streams connected to the FAB. Thus, you need not explicitly issue a 
Disconnect service prior to closing the file. However, if more than one RAB 
is connected to a single FAB, then you must explicitly disconnect the desired 
RAB in order to terminate a particular record stream and leave the others 
active. 

Table RMS-11 lists the control block fields read as input by the Disconnect 
service. For additional information on the fields accessed by this service, 
see Part II. 

Table RMS-11 Disconnect RAB Input Fields 

Field Name Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$I_ROP Record-processing option, RAB$V_ASY. Asynchronous: 

performs Disconnect service asynchronously. 


Table RMS-12 lists the control block fields written as output by the 
Disconnect service. 

Table RMS-12 Disconnect RAB Output Fields 

Field Name Description 

RAB$W_JSI Internal stream identifier (zeroed). 

RAB$I—STS Completion status code (also returned in Register 0). 

RAB$I_STV Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMSS—DNR 

RMS$_NORMAL 

RMS$_STR 

RMS$_SYS 


RMS$_ATR 

RMS$_CDA 

RMS$_ISI 

RMS$_PENDING 

RMS$_SUC 

RMS$_WBE 


RMS$_ATW 

RMS$_CRC 

RMS$_NET 

RMS$_RAB 

RMS$_SUP 

RMS$_WER 


RMS$_BLN 

RMS$_DME 

RMS$_NETFAIL 

RMS$_RSA 

RMS$_SUPPORT 

RMS$_WLK 
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$DISPLAY 



The Display service retrieves file attribute information about a file 
and places this information in fields in the FAB, in XABs chained to 
the FAB, and in a NAM block (if requested). 

FORMAT 

SYS$DISPLAY fab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for 
the Display service call. The fab argument is the address of the FAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Display service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION a file must be open for access by a Create or Open service before the Display 
service can be invoked. 

VAX RMS places the file attribute information in the corresponding fields of 
the FAB and specified XABs. If the FAB$L_NAM field contains a valid NAM 
block address, certain NAM block fields are filled in, including the resultant 
string, and the NAM$B_NOP options are examined. 

Note that the Open and Create services automatically perform an implicit 
Display service (see $OPEN, $CREATE). 

Table RMS-13 lists the control block fields read as input by the Display 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-13 Display FAB and NAM Input Fields 


Field Name 

Option 

Description 

FAB$W_IFI 


Internal file identifier. 

FAB$I_ 

NAM 1 


Name block address. 

FAB$I_XAB 1 


Extended attribute block address. 

NAM$B_NOP 


NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word "password”). 


NAM$V_NOCONCEAL 

Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by 
the actual physical device name (and 
directory, if present) in the resultant 
string. 


^he appropriate XAB or NAM block must be specified on input, if you desire 
information about that particular XAB or NAM block on output from the Display 
service. 


Table RMS-14 lists the control block fields written as output by the Display 
service. 

Table RMS—14 Display FAB, NAM, and XAB Output Fields 

Field Name 

XAB Type Description 

FAB$I ALQ 

Allocation quantity in blocks. 

FAB$B_BKS 

Bucket size. 

FAB$W_BLS 

Block size. 

FAB$W_DEQ 

Default file extension quantity. 

FAB$L_DEV 

Device characteristics. 
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Table RMS-14 (Cont.) Display FAB, NAM, and XAB Output 

Fields 


Field Name 

XAB Type 

Description 

FAB$B_FAC 


File access. 

FAB$B_FSZ 


Fixed control area size. 

FAB$W_GBC 


Global buffer count. 

FAB$L_MRN 


Maximum record number. 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes. 

FAB$B_RFM 


Record format. 

FAB$B_RTV 


Retrieval window size. 

FAB$B_SHR 


File sharing. 

FAB$L_STS 


Completion status code (also returned in 
Register 0). 

FAB$L_STV 


Status value. 

FAB$L_XAB 


Next XAB address. 


XABALL 

Allocation XAB; see Section 8. 


XABDAT 

Date and time XAB; see Section 9. 


XABFHC 

File header characteristics XAB; 
see Section 10. 


XABKEY 

Key definition XAB; see Section 11. 


XABPRO 

Protection XAB; see Section 12. 


XABRDT 

Revision date and time XAB; see Section 13. 


XABSUM 

Summary XAB; see Section 14. 

NAM$W_DID 


Directory identification. 

NAM$T_DVI 


Device identification. 

NAM$W_FID 


File identification. 

NAM$I_FNB 


File name status bits. 

NAM$B_RSL 


Resultant string length: indicates the length 
of the resultant string that is written into 
the buffer whose address is contained in the 
NAM$L_RSA field (if the NAM$L_RSA and 
NAM$B_RSS fields are nonzero). 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 
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RMS$_ACT 

RMS$_BUG_DAP 

RMSS—DNR 

RMS$_FAB 

RMSS—NETFAIL 

RMSS—PRV 

RMS$_SUC 


RMS$_AID 

RMS$_CDA 

RMS$_ESA 

RMS$_IFI 

RMS$_NORMAL 

RMS$_REF 

RMS$_SUP 


RMSS—ATR 

RMSS—COD 

RMS$_ESL 

RMS$_IMX 

RMS$_OK_NOP 

RMS$_RPL 

RMS$_SUPPORT 


RMS$_BLN 

RMS$_DME 

RMS$_ESS 

RMS$_NET 

RMS$_PLG 

RMS$_STR 

RMSS—XAB 
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$ENTER 

The Enter service inserts a file name into a directory. 

FORMAT 

SYSSENTER fab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in R0 is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Enter service call. The fab argument is the address of the FAB control block. 


err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Enter service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 


DESCRIPTION The Enter service function is performed automatically by the Create service 

unless the FAB$L_FOP field FAB$V_TMP or FAB$V_TMD option is set. The 
Enter service, however, allows you to perform this step separately. Note that 
the file must be closed before invoking the Enter service (FAB$W_IFI must be 
0 ). 

When you enter a file name into a directory, no file associated with the FAB 
can be open and no wildcard characters can be used. 
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The Enter service requires many NAM block fields as input. You normally 
precede the Enter service with an Open, Create, or Parse service (see SPARSE) 
and a Search service (see SSEARCH), specifying the same FAB and NAM 
block for each service. 

The optional resultant string is moved to the buffer described by the 
NAM$L_RSA and NAM$B_RSS fields (only if both these fields are nonzero). 
If the file version number of the name string described by the expanded string 
length and address fields of the NAM block is either not present or 0, the 
Enter service scans the entire directory. It assigns a version number that is 
one higher than the highest found (or 1 if none is found). 

The Enter service is not supported for DECnet operations with remote files 
between two VAX/VMS systems. 

Table RMS-15 lists the control block fields read as input by the Enter service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-15 Enter FAB and NAM Input Fields 


Field Name 

Description 

FAB$W_IFI 

Internal file identifier (must be 0). 

FAB$I_NAM 

Name block address. 

NAMSW—DID 1 

Directory identification: identifies the directory where the file 
name is to be entered. 

NAMST—DVI 1 

Device identification: identifies the device containing directory 
where file name is to be entered. 

NAM$1_ESA 

Expanded string area address: contains file name, type, and 
version to be entered. 

NAM$B_ESL 

Expanded string length. 

NAMSW—FID 1 

File identification: identifies the file to be entered into the 
directory. 

NAM$I_RSA 

Resultant string area address. 

NAM$B_RSS 

Resultant string size. 

1 Not supported for DECnet operations 

Table RMS-16 lists the control block fields written as output by the Enter 

service. 


Table RMS-16 

Enter FAB and NAM Output Fields 

Field 

Name 

Description 

FAB$I_STS 

Completion status code (also returned in Register 0). 

FAB$L_STV 

Status value. 

NAM$B_RSL 

Resultant string length. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 
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RMS$_BLN 

RMSS—DME 

RMS$_ENT 

RMS$_FNF 

RMS$_PRV 

RMS$_STR 

RMS$_SYS 


RMS$_CDA 

RMS$_DNF 

RMS$_ESA 

RMS$_IFI 

RMS$_RSL 

RMS$_SUC 

RMS$_WLD 


RMS$_CHN 

RMS$_DNR 

RMS$_ESL 

RMS$_NAM 

RMS$_RSS 

RMS$_SUP 

RMS$_WLK 


RMS$_DEV 

RMS$_DVI 

RMS$_FAB 

RMS$_NORMAL 

RMS$_RST 

RMS$_SUPPORT 
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$ERASE 

The Erase service deletes a VAX RMS disk file and removes the 
file’s directory entry as specified in the path to the file. If additional 
directory entries have been created for this file (by use of the Enter 
service), then you must use the Remove service to delete them. 

FORMAT 

SYSSERASE fab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Erase service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Erase service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION Using the Erase service to delete a file releases the file's allocated space for 

use by another file. The Erase service does not physically remove the data (as 
does overwriting or zeroing). 

Note that the file must be closed before invoking the Erase service (FAB$W_ 
IFI must be zero). You can, however, delete a file that is currently open, if 
you issue a Close service and specify the FAB$L_FOP field FAB$V_DLT 
option. VAX RMS does not allow you to delete files from magnetic tape 
volumes; they must be overwritten. 

If a search list logical name is specified, the file is deleted only if it is found in 
the first resulting search list file specification. 

Table RMS-17 lists the control block fields read as input by the Erase service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-17 Erase FAB and NAM Input Fields 


Field Name 

Option 

Description 

FAB$L_DNA 


Default file specification string address. 

FAB$B_DNS 


Default file specification string size. 

FAB$I_FNA 


File specification string address. 

FAB$B_FNS 


File specification string size. 

FAB$I_FOP 


File-processing options. 


FABSV—NAM 1 

Use NAM block inputs: allows use of the 
NAM$W_DID, NAM$T_DVI, and NAM$W_ 
FID fields. 

FAB$W_IFI 


Internal file identifier (must be 0). 

FAB$I_NAM 


Name block address. 

NAMSW-DID 1 


Directory identification (input only if the 
FAB$L_F0P field FAB$V_NAM bit is set). 

NAMST^DVI 1 


Device identification (input only if the 
FAB$L_FOP field FAB$V_NAM bit is set). 

NAM$L_ESA 


Expanded string area address. 

NAM$B_ESS 


Expanded string area size. 

NAMSW—FID 1 


File identification (input only if the FAB$L_ 
FOP field FAB$V_NAM bit is set). 

NAM$L_RLF 


Related file NAM block address. 


NAM$I_RSA 

Related file resultant string address. 


NAM$B_RSS 

Related file resultant string size. 


NAM$L_FNB 

Related file filename status bits. 


1 Not supported for DECnet operations 


Table RMS-18 lists the control block fields written as output by the Erase 
service. Note that the NAM block fields are used for output only if the name 
block address field is specified in the FAB. 
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Table RMS-18 Erase FAB and NAM Output Fields 


Field Name 

Description 

FAB$L_STS 

Completion status code (also returned in Register 0). 

FAB$L_STV 

Status value. 

NAMSW-DID 1 

Directory identification. 

NAMST—DVI 1 

Device identification. 

NAM$B_ESL 

Expanded string length (if, on input, both the NAM$L_ESA 

and NAM$B_ESS are nonzero, and if the FAB$I_FOP field 

FAB$V_NAM bit is clear or the NAM$W_DID field is 0, 
the expanded file specification string is copied to the buffer 
specified by the input NAM$L_ESA field). 

NAM$I_FNB 

File name status bits. 

NAM$B_RSL 

Resultant string length (if NAM$I_RSA and NAM$B_RSS are 

both nonzero on input, the resultant file specification is copied 
to the buffer specified by NAM$L_RSA). 

1 Not supported for DECnet operations. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMSS—ACS 

RMSS—BLN 

RMS$_BUG_DAP 

RMS$_BUG_DDI 

RMSS—CDA 

RMS$_CHN 

RMS$_DEV 

RMS$_DIR 

RMS$_DME 

RMS$_DNA 

RMSS—DNF 

RMS$_DNR 

RMS$_DVI 

RMS$_ESA 

RMS$_ESS 

RMS$_FAB 

RMS$_FNF 

RMSS—FNM 

RMS$_IFI 

RMS$_IOP 

RMS$_LNE 

RMS$_MKD 

RMS$_NAM 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NOD 

RMS$_NORMAL 

RMSS—PRV 

RMS$_QUO 

RMS$_RLF 

RMS$_RSS 

RMS$_RST 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPERSEDE 

RMS$_SUPPORT 

RMS$_SYN 

RMS$_TYP 

RMS$_VER 


RMS$_WLK 
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$EXTEND 

The Extend service increases the amount of space allocated to a 
VAX RMS disk file. This service is most useful for relative and 
indexed files when performing block I/O using the Write service. 

FORMAT 

SYSSEXTEND fab[,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L__STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Extend service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Extend service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Extend service is performed automatically as data is placed into a file, 
regardless of the file's organization. However, when using block I/O, only 
sequential files are automatically extended. Thus, you must use the Extend 
service for relative and indexed files when using block I/O. Also, you may 
wish to extend a file explicitly for performance reasons, such as placing a 
large file extent (an extended part of a file) contiguous to the file. 
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You must open the file (FAB$W_IFI must not be 0) before invoking the 
Extend service; otherwise, an error occurs. The file sharing field (FAB$B_ 
FAC) must specify put (FAB$Y_PUT) or update (FAB$V_UPD) access to the 
file to be extended. 

The allocation quantity (FAB$L_ALQ) field or the allocation XAB (XAB$L_ 
ALQ) field, (if an XABALL is used) must contain the number of blocks that 
VAX RMS is to add to the file. Furthermore, you can indicate other attributes 
regarding the manner and location for allocation. For example, you can 
indicate that the additional blocks must be allocated contiguously. If you do 
specify contiguous space and if not enough contiguous space is available, the 
operation will fail. (This extension will not be contiguous with the initial file 
space.) 

If an allocation control XAB is present, its allocation quantity (XAB$L_ALQ) 
and allocation options (XAB$B_AOP, XAB$V_CBT and XAB$V_CTG bits 
only) fields are used instead of the corresponding fields in the FAB. The 
allocation quantity field of the XAB is set to the actual extension size. You 
may specify multiple XABs to extend separate areas of indexed files. 

Table RMS-19 lists the control block fields read as input by the Extend 
service. For additional information on the fields accessed by this service. 


see Part II. 


Table RMS- 

-19 Extend FAB Input Fields 

Field Name 

Description 

FAB$I_ALQ 

Allocation quantity; ignored if an allocation XAB is present. 

FAB$I_FOP 

File-processing options: checked to see whether the FAB$V_ 
CTG or FAB$V_CBT bit is set to indicate contiguous allocation 
(ignored if allocation XAB is present). 

FAB$W_IFI 

Internal file identifier (must not be 0). 

FAB$I_XAB 

Extended attribute block address. Only an allocation XAB 
(XABALL) will be processed. 


Table RMS-20 lists the control block fields written as output by the Extend 
service. 

Table RMS-20 Extend FAB Output Fields 

Field Name Description 

FAB$L_ALQ Allocation quantity: contains the actual extension allocation 

value if no allocation XAB is present. 

FAB$I_STS Completion status code (also returned in Register 0). 

FAB$I_STV Status value (contains the total number of blocks allocated, 

totaled across all allocation XABs). 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 
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RMS$_ACT 

RMS$_AID 

RMSS—ALN 

RMS$_ALQ 

RMSS—AOP 

RMS$_ATR 

RMS$_ATW 

RMS$_BLN 

RMS$_BUG_DAP 

RMSS—CDA 

RMSS—COD 

RMS$_DME 

RMS$_EXT 

RMS$_FAB 

RMS$_FAC 

RMS$_FUL 

RMS$_IFI 

RMS$_IMX 

RMS$_IOP 

RMS$_LEX 

RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_PLG 

RMS$_RPL 

RMSS—STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 

RMS$_WBE 

RMS$_WER 

RMS$_WLK 

RMS$_WPL 

RMS$_XAB 
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$FIND 

The Find service locates a specified record in a file and returns its 
record's file address in the RAB$W_RFA field of the RAB. The Find 
service can be used with ail file organizations. 

FORMAT 

SYSSFIND rab[,[err][,suc]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Find service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Find service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION The Find service allows you to do the following: 

• Skip records when accessing a file sequentially (by issuing successive Find 
services) 

• Lock, but not retrieve, a record, thereby establishing a current record for 
an Update, Delete, or Truncate service 

• Establish a random access starting point in a file for subsequent sequential 
access 

• Directly access records by key value for Delete or Update services, without 
modifying the next record context of sequential operations on the same 
stream 

Table RMS-21 lists the control block fields read as input by the Find service. 

For additional information on the fields accessed by this service, see Part II. 


Table RMS-21 Find RAB Input Fields 


Field Name 

XAB Type 

Description 

RAB$W_ISI 


Internal stream identifier (required). 

RAB$I_KBF 


Key buffer address (used only if RAB$B_ 
RAC field contains RAB$C_KEY or if 
RAB$B_RAC contains RAB$C_SEQ and the 
RAB$L_ROP field RAB$V_LIM option is 
set). 

RAB$B_KRF 


Key of reference (used only with indexed 
files and if RAB$B_RAC contains RAB$C_ 
KEY). 

RAB$B_KSZ 


Key size (used only if RAB$B_RAC field 
contains RAB$C_KEY or if RAB$B_RAC 

contains RAB$C_SEQ and the RAB$I_ROP 

field RAB$V_LIM option is set). 

RABSL—PBF 1 


Prompt buffer address (applies to terminal 
devices only). 

RABSB—PSZ 1 


Prompt buffer size (applies to terminal 
devices only). 

RAB$B_RAC 


Record access mode (RAB$C_SEQ, 
RABSC—KEY, RAB$C_RFA) 2 . 

RAB$W_RFA 


Record's file address (used only if RAB$B_ 
RAC contains RAB$C_RFA). 

RAB$I_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Find services 
asynchronously. 


RABSV—CVT 1 

Convert: changes characters to uppercase 
for a Find service to a terminal device. 


RAB$V_KGE 3 

Key is greater than or equal to (applies only 
to indexed files). 


1 Not supported for DECnet operations 

2 The default for the RAB$B_RAC field is RAB$C_SEQ. 

3 Logically synonymous with RAB$V_EQNXT 
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Table RMS-21 (Cont.) Find RAB Input Fields 


Field Name XAB Type 

Description 

RAB$V_KGT 4 

Key is greater than (applies only to indexed 
files). If neither RAB$V_KGE nor RAB$V_ 
KGT is specified, a key equal match is 
made. 

RAB$V_LIM 

Limit: the key value described by the KBF 
and KSZ fields is to be compared to the 
value in the record accessed sequentially. 

RAB$V_NLK 

No lock: specifies that the record accessed 
through the Find service is not to be locked. 

RAB$V_NXR 

Nonexistent record processing: specifies 
that if the record directly accessed through 
a Find service does not exist, the service is 
to be performed anyway. 

RAB$V_PMT 1 

Prompt indicates that the contents of the 
prompt buffer are to be used as a prompt 
for a Find service to a terminal device. 

RABSV—PTA 1 

Purge type-ahead: eliminates any 
information that may be in the type-ahead 
buffer, for a Find service to a terminal 
device. 

RAB$V_RAH’ 

Read ahead: used with multiple buffers to 
indicate read-ahead operations (sequential 
files only). 

RAB$V_REA 

Lock for read: allows other users read- 
access to the record. 

RAB$V_RLK 

Read of locked record allowed: specifies 
that a user who locks a record is allowing 
the locked record to be read by other 
accessors. 

RABSV—RNE 1 

Read no echo: indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 

RAB$V_RNF 1 

Read no filter: indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered control commands on terminal 
input, but are to be passed to the user 
program. 

RAB$V_RRL 

Read regardless of lock: read the record 
even if another stream has locked the 
record. 

RABSV—TMO 1 

Timeout: indicates that the contents of 
the timeout period field (RAB$B_TMO) is 
to be used on a Find request for locked 
record (when the RAB$V_WAT option is 
also specified) or for a terminal or mailbox 
device. 


1 Not supported for DECnet operations 
4 Logically synonymous with RAB$V_NXT 
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Table RMS-21 (Cont.) Find RAB Input Fields 


Field Name 

XAB Type 

Description 


RAB$V_ULK 

Manual unlocking: specifies that record 
cannot be automatically unlocked. 


RAB$V_WAT 

Wait: if record is locked, wait until it is 
available. 

RABSB—TMO 1 


Timeout period: indicates the maximum 
number of seconds that VAX RMS can use 
to complete a Find request. 

1 Not supported for DECnet operations 


Table RMS-22 lists the control block fields written as output by the Find 
service. 


Table RMS-22 Find RAB Output Fields 


Field Name 

Description 

RAB$I_BKT 

Bucket code: set to the relative record number for relative files 
accessed sequentially. 

RAB$W_RFA 

Record's file address. 

RAB$I_STS 

Completion status code (also returned in Register 0). 

RAB$I_STV 

Status value. 


The record address (RAB$L__RBF) and record size (RAB$W_RSZ) fields are 
undefined after a Find service. 


CONDITION 

VALUES 

The following condition values are described in 

Appendix A: 

RETURNED 


RMS$_ACT 

RMS$_ANI 

RMS$_ATR 


RMS$_ATW 

RMS$_BES 

RMS$_BLN 


RMS$_BUG 

RMS$_BUG_DAP 

RMS$_CDA 


RMS$_CHK 

RMS$_CONTROLC 

RMS$_CONTROLY 


RMS$_DEADLOCK 

RMS$_DEL 

RMS$_DME 


RMS$_DNR 

RMS$_EOF 

RMS$_EXENQLM 


RMS$_FAC 

RMS$_FTM 

RMS$_IBF 


RMS$_IOP 

RMS$_IRC 

RMS$_ISI 


RMS$_KBF 

RMS$_KEY 

RMS$_KRF 


RMS$_KSZ 

RMS$_MRN 

RMS$_NET 


RMS$_NETFAIL 

RMS$_NORMAL 

RMS$_0K_ALK 


RMS$_OK_DEL 

RMS$_OK_LIM 

RMS$_OK_RLK 


RMS$_OK_RNF 

RMS$_OK_RRL 

RMS$_OK_WAT 


RMS$_PBF 

RMSS—PENDING 

RMS$_PES 
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RMS$_PLG 

RMS$_RAB 

RMS$_RAC 

RMS$_REF 

RMS$_RER 

RMS$_RFA 

RMS$_RHB 

RMS$_RLK 

RMSS—RNF 

RMS$_ROP 

RMS$_RPL 

RMS$_RRV 

RMS$_RSA 

RMS$_SQO 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 

RMS$_TMO 

RMS$_TRE 

RMS$_WBE 

RMS$_WER 

RMS$_WLK 
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$FLUSH 

The Flush service writes out all modified I/O buffers and file 
attributes associated with the file. This ensures that all record 
activity up to the point at which the Flush service executes is actually 
reflected in the file. 

FORMAT 

SYS$FLUSH rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L__STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Flush service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Flush service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION The Flush service is not required at any time, not even with a Close service, 
because the Close service performs the Flush functions implicitly. 

During asynchronous operations, you must wait for any I/O activity to 
complete before issuing a Flush service. You may also issue a Flush service 
after receiving notification of completion through an asynchronous system 
trap (AST). 

Table RMS-23 lists the control block fields read as input by the Flush service 
For additional information on the fields accessed by this service, see Part II. 

Table RMS-23 Flush RAB Input Fields 

Field Name Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$L_ROP Record-processing option: RAB$V_ASY only. Asynchronous: 

performs Flush services asynchronously. 


Table RMS-24 lists the control block fields written as output by the Flush 
service. 


Table RMS-24 Flush RAB Output Fields 


Field Name 

Description 

RAB$L_STS 

RABSL—STV 

Completion status code (also returned in Register 0). 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMS$_ISI 

RMS$_PENDING 

RMS$_SUC 

RMS$_WBE 


RMS$_ATR 

RMSS—CDA 

RMS$_NET 

RMS$_RAB 

RMS$_SUP 

RMS$_WER 


RMS$_ATW 

RMS$_DME 

RMS$_NETFAIL 

RMS$_RSA 

RMS$_SUPPORT 

RMS$_WLK 


RMS$_BLN 

RMSS—DNR 

RMS$_NORMAL 

RMS$_STR 

RMS$_SYS 
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$FREE 

The Free service unlocks all records that were previously locked for 
the record stream. 

FORMAT 

SYSSFREE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Free service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Free service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Free service unlocks all records previously locked for the record stream 
(see also $RELEASE). If no records are locked for the record stream, VAX 
RMS returns a status code of RMS$_RNL. 
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Table RMS-25 lists the control block fields read as input and written as 
output by the Free service. For additional information on the fields accessed 
by this service, see Part II. 


Table RMS-25 Free RAB Input and Output Fields 


Use 

Field 

Name 

Description 

Input 

RAB$W_ISI 

Internal stream identifier (required). 

Output 

RAB$L_STS 

Completion status code (also returned in Register 0). 


RAB$L_STV 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMSS—NET 

RMS$_RAB 

RMS$_SUC 


RMS$_BLN 

RMS$_NETFAIL 

RMS$_RNL 

RMS$_SUP 


RMS$_BUG_DAP 

RMS$_NORMAL 

RMS$_RSA 

RMS$_SUPPORT 


RMS$_ISI 

RMS$_PENDING 

RMS$_STR 
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$GET 

The Get service retrieves a record from a file. 

FORMAT 

SYSSGET rab [,[err] [,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Get service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Get service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Get service is performed by using one of three possible record access 
modes, as specified by the record access (RAB$B_RAC) field. The three 
modes are sequential (SEQ), which is the default, random by key (KEY), and 
random by record's file address (RFA), also called RFA access. 
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Relevant Record Access Modes 

The sequential access mode is relevant for all file organizations as well as for 
all devices. It is the only access mode allowed for nondisk devices, such as 
terminals, mailboxes, and magnetic tape devices. In this mode, records are 
retrieved from a given file in the same order in which they were written to 
that file. This is not the case, however, for records retrieved from indexed 
files. Sequential Get services for indexed files return records by key value in 
the specified sort order, ascending or descending. The next record's key of 
reference for sequential access to indexed files is established by one of the 
following services: 

• Connect 

• Rewind (see $REWIND) 

• Find or Get using random-by-key access 

• Find or Get using random-by-RFA access 

When you use the random-by-key access with any operations related to 
these services, the key of reference is established by the key of reference field 
(RAB$B_KRF). When using random-by-RFA access in conjunction with a Find 
or Get service, however, the key of reference is always set to the primary key. 

You can use random-by-key access mode to retrieve records by key value. 

For relative files and sequential files having 512-byte, fixed-length records, 
the key value is the relative record number. For indexed files, the key value 
is dependent on the data type of the specified key of reference. The key 
value is used to search the index of the specified key of reference to locate the 
desired record. A random-by-key access also establishes the next record for 
subsequent sequential retrieval. This type of access may be used in this way 
to establish a starting point for sequential retrieval of records at other than 
the beginning of the file. 

You can use random-by-RFA access to retrieve records directly from files 
residing on disk devices. However, a record's address can be determined only 
if the record has been accessed previously. The Find, Get, and Put services 
each return the RFA value as output in the RAB$W__RFA field. 

Random access of records in a file is prohibited when you open the file 
with the FAB$L_FOP field FAB$V_SQO option set; that is, if you specify 
sequential operations only. 

Input from Stream Format Files 

For stream format files, VAX RMS fills the user buffer with data until a 
terminator is reached. If the buffer fills before a terminator is encountered, 
the remainder of the data preceding the terminator is discarded, and an 
RMS$_RTB error will be returned. If the terminator for stream format 
(FAB$B_RFM contains FAB$C_STM) is not CRLF (carriage return followed 
by line feed), the terminator will be stored in the buffer following the record 
and included in the size of the record. 
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Input From Terminal Devices 

There are two methods of obtaining input from a terminal using VAX RMS: 

1 Using the RAB$L_ROP field to define the terminal input operation. 
Certain options applicable to the RAB$L_ROP field are used for terminal 
device input, such as whether a prompt is to be displayed and whether a 
time limit between characters will be enforced. These options may require 
certain information to be placed in other fields of the RAB (see Section 7). 
The maximum buffer size is 512 bytes. 

2 Using an item list to define the terminal input operation, in conjunction 
with a Terminal XAB (XABTRM). The ETO option of the RAB$L__ROP 
field must be set and the user must provide an item list in the calling 
program, which VAX RMS passes to the terminal driver using the item 
list address and length specified in the XABTRM (see Section 15). This 
method allows use of any terminal input option supported by the terminal 
driver, in contrast to the subset of RAB$L_ROP options available using 
the other method. The maximum buffer size is 512 bytes. 

VAX RMS uses the standard terminator set when performing input operations 
from terminal devices. The second longword of the I/O status block used 
is returned in the RAB$L_STV field. The terminating character is returned 
in the lower word of the status value field (RAB$W_STV0); however, note 
that with extended terminal operations, the terminating character is in the 
first byte of RAB$W_STV0, not in the entire RAB$W_STV0 word. More 
information about the second longword of the I/O status block is available 
in the VAX/VMS I/O User's Reference Manual: Part I and the VAX/VMS I/O 
Reference Volume. The RAB$W_STV0 field is device-dependent for terminal 
devices. 

In addition to terminating the Get service, the CTRL/Z character is treated 
as an end-of-file marker by VAX RMS. If you enter a CTRL/Z response to 
a read request, VAX RMS will return the completion status code for end-of- 
file (RMS$_EOF). Data entered before the execution of the CTRL/Z will be 
returned successfully. The next Get service will return a single end-of-file 
error (RMS$_EOF) without accepting any further input from the device. You 
can resume the acceptance of input from the device, however, by requesting a 
subsequent Get service. 

VAX RMS also supports the use of escape sequences from terminal devices 
that are accessed locally and have escape sequences enabled. Escape 
sequences for a terminal are enabled by the SET TERMINAL command 
(described in the VAX/VMS DCL Dictionary). Escape sequences are returned 
in the record buffer. The record size (RAB$W_RSZ) is the offset within the 
buffer (RAB$L_RBF) to the beginning of the escape sequence. The high-order 
word of the status value field (RAB$W_STV2) will contain the length of the 
escape sequence, except for extended terminal operations. In this case, the 
escape sequence length is returned in the first byte of RAB$W_STV2, not 
the entire RAB$W_STV2 word, and the terminator position is returned in 
the second byte of the RAB$W_STV2 word. When a partial escape sequence 
warning (RMS$_PES) is returned, the remaining characters in the escape 
sequence will be returned by the next read request from the terminal. 
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Input From Mailbox Devices 

Mailboxes may be used to synchronize activity across cooperating processes. 
Normally, a Get service from a mailbox device will not be completed until 
a record is present in the mailbox. When the Get service is completed, the 
status value field (RAB$L_STV) will contain the process identification (PID) 
of the process that put the record into the mailbox. However, if the timeout 
(TMO) record option is specified with a value of 0 in the timeout field and 
if no messages are present in the mailbox, then the Get service will return 
an end-of-file error (RMS$_EOF). This technique assures your process of an 
immediate return, whether or not messages are present in the mailbox. 

Use of the RAB$I_STV Field 

The RAB$L_STV field contains additional status information for a number of 
situations. When the completion status is a record-too-big warning (RMS$_ 
RTB), RAB$L_STV contains the total record size. When the device is record 
oriented (for example, terminals and mailboxes), the second longword of 
the I/O status block is returned in the RAB$L__STV field, whenever the 
completion status (RAB$L_STS) is a success code. The alternate field 
definitions of RAB$W_STV0 and RAB$W_STV2 are provided to reference 
the respective low- and high-order words of the RAB$L_STV field. The 
record size field (RAB$W_RSZ) always reports the amount of data returned, 
regardless of the completion status (RAB$L_STS). The presence of valid data 
on error conditions may then be detected by checking the record size field. 

The User Record Area 

The Get service always requires the presence of a user record area, as 
specified by the user record area address (RAB$L_UBF) and user record 
area size (RAB$W_USZ) fields in the RAB. 

For undefined format files, the RAB$W_USZ field defines the amount of data 
to be returned on each Get service. 

Table RMS-26 lists the control block fields read as input by the Get service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-26 Get RAB Input Fields 


Option or 

Field Name XAB Type 

RAB$W_ISI 

RAB$L_KBF 


RAB$B_KRF 

RAB$B_KSZ 


Description 

Internal stream identifier (required). 

Key buffer address (used only if RAB$B_ 
RAC field contains RAB$C_KEY or if 
RAB$B_RAC contains RAB$C_SEQ and 
the RAB$L_ROP field RAB$V_LIM option 
is set). 

Key of reference (used only with indexed 
files and if RAB$B_RAC contains 
RAB$C_KEY). 

Key buffer size (used only if RAB$B_ 
RAC field contains RAB$C_KEY or if 
RAB$B_RAC contains RAB$C_SEQ and 
the RAB$L_ROP field RAB$V_LIM option 
is set). 
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Table RMS-26 (Cont.) Get RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RABSL—PBF 1 


Prompt buffer address (applies to 
terminal devices only). 

RABSB—PSZ 1 


Prompt buffer size (applies to terminal 
devices only). 

RAB$B_RAC 


Record access mode (RAB$C_SEQ, 
RAB$C_KEY, RAB$C_RFA) 2 . 

RAB$W_RFA 


Record's file address (used only if 
RAB$B_RAC field contains RAB$C_ 

RFA). 

RAB$I_RHB 


Record header buffer: used for the fixed 
control portion of variable with fixed 
control (VFC) records. 

RABSI_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Get services 
asynchronously. 


RABSV—CVT 1 

Convert: changes characters to 
uppercase for a Get service to a terminal 
device. 


RABSV—ETO 1 

Extended terminal operation: indicates 
that an XABTRM and an item list is 
present to define the terminal input 
operation. If this option is specified, no 
other RAB$L_ROP options applicable to 
terminal devices can be used. 


RAB$V_KGE 3 

Search for equal key value or next key 
value according to sort order (applies 
only to indexed files). 


RAB$V_KGT 4 

Search for next key value according 
to sort order; if neither RAB$V_KGE 
(RAB$V_EQNXT) nor RAB$V_KGT 
(RAB$V_NXT) is specified, a key equal 
match is made. 


RAB$V_LIM 

Limit: the key value described by the 
RAB$L_KBF and RAB$B_KSZ fields is to 
be compared to the value in the record 
accessed sequentially. 


RABSV-LOC 1 

Locate mode: indicates that record 
operations involving the Get service will 
use locate mode. 


RAB$V_NLK 

No lock: specifies that the record 
accessed through the Get service is 
not to be locked. 


1 Not supported for DECnet operations 
2 The default for the RAB$B_RAC field is RAB$C_SEQ. 
3 Logically synonymous with RAB$V_EQNXT 
4 Logically synonymous with RAB$V_NXT 
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Table RMS-26 (Cont.) Get RAB Input Fields 


Option or 

Field Name XAB Type 

Description 

RAB$V_NXR 

Nonexistent record processing: specifies 
that if the record directly accessed 
through a Get service does not exist, the 
service is to be performed anyway. 

RABSV—PMT 1 

Prompt: indicates that the contents of 
the prompt buffer are to be used as a 
prompt on a Get service to a terminal 
device. 

RABSV—PTA 1 

Purge type-ahead: eliminates any 
information that may be in the type- 
ahead buffer, on a Get service to a 
terminal device. 

RABSV—RAH 1 

Read ahead: used with multiple buffers 
to indicate read-ahead operations 
(sequential files only). 

RAB$V_REA 

Lock for read: allows other users read- 
access to the record. 

RAB$V__RLK 

Read of locked record allowed: specifies 
that a user who locks a record for 
modification is allowing the locked record 
to be read by other accessors. 

RABSV—RNE 1 

Read no echo indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 

RABSV—RNF 1 

Read no filter: indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered control commands on 
terminal input, but are to be passed 
to the user program. 

RAB$V_RRL 

Read regardless of lock: read the record 
even if another stream has locked the 
record. 

RABSV-TMO 1 

Timeout: indicates that the content of 
the timeout period field (RAB$B_TMO) is 
to be used. 

RAB$V_ULK 

Manual unlocking: specifies that records 
cannot be automatically unlocked. 

RAB$V_WAT 

Wait: if record is locked, wait until it is 
available. 


1 Not supported for DECnet operations 
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CONDITION 

VALUES 

RETURNED 


Table RMS-26 (Cont.) Get RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RABSB—TMO 1 


Timeout period: indicates the maximum 
number of seconds that VAX RMS 
will allow between characters for a 

Get service to terminal and mailbox 
devices only, or the maximum number of 
seconds VAX RMS will wait for a locked 
record (if RAB$L_ROP RAB$V_TMO and 
RAB$V_WAT options are specified). 

RAB$L_UBF 


User record area address (required). 

RAB$W_USZ 


User record area size (required). 

RAB$I_XAB 

XABTRM 1 

Next XAB address: indicates address of 
an XABTRM control block (the RAB$L_ 
ROP field RAB$V_ETO option must be 
set for an extended terminal operation). 

1 Not supported for DECnet operations 


Table RMS-27 lists the control block fields written as output by the Get 
service. 


Table RMS-27 Get RAB Output Fields 


Field Name 

Description 

RAB$I_BKT 

Bucket code: set to the relative record number for relative files 
when the record access mode is sequential. 

RABSL—RBF 

Record buffer address. 

RAB$W_RFA 

Record's file address. 

RAB$W_RSZ 

Record size. 

RAB$I_STS 

Completion status code (also returned in Register 0). 

RAB$1_STV 

Status value (contains a terminator character for terminal input 
or the record length if the requested record is too large for the 
user buffer area). 


The following condition values are described in Appendix A: 


RMSS—ACT 

RMS$_BLN 

RMS$_CDA 

RMS$_CONTROLY 

RMSS—DME 

RMS$_ENQ 

RMS$_FAC 


RMS$_ANI 

RMS$_BUG 

RMSS—CHK 

RMS$_DEADLOCK 

RMS$_DNR 

RMS$_EXENQLM 

RMS$_FTM 


RMS$_BES 

RMS$_BUG_DAP 

RMS$_CONTROLC 

RMS$_DEL 

RMS$_EOF 

RMS$_EXP 

RMS$_IBF 
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RMS$_IOP 

RMS$_KBF 

RMS$_KSZ 

RMS$_NETFAIL 

RMS$_OK_DEL 

RMS$_OK_RNF 

RMS$_PBF 

RMS$_PLG 

RMS$_RER 

RMS$_RLK 

RMS$_RPL 

RMS$_RTB 

RMS$_SUC 

RMS$_SYS 

RMS$_TRE 

RMS$_WER 
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RMS$_IRC 

RMS$_KEY 

RMS$_MRN 

RMS$_NORMAL 

RMS$_OK_LIM 

RMS$_OK_RRL 

RMS$_PENDING 

RMS$_RAB 

RMS$_RFA 

RMS$_RNF 

RMS$_RRV 

RMS$_SQO 

RMS$_SUP 

RMS$_TMO 

RMS$_UBF 

RMS$_WLK 


RMS$_ISI 

RMS$_KRF 

RMS$_NET 

RMS$_OK_ALK 

RMS$_OK_RLK 

RMS$_OK_WAT 

RMS$_PES 

RMS$_RAC 

RMS$_RHB 

RMS$_ROP 

RMS$_RSA 

RMS$_STR 

RMS$_SUPPORT 

RMS$_TNS 

RMS$_WBE 

RMS$_XAB 
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$NXTVOL 



The Next Volume service allows you to process the next tape 
volume in a multiple volume set. This service applies only to files on 
magnetic tape volumes. 

FORMAT 

SYSSNXTVOL rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Next Volume service call. The rab argument is the address of the RAB 
control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Next Volume service invokes 
if the operation is successful. The sue argument is the address of the entry 
mask of this user-written completion routine. 
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DESCRIPTION You use the Next Volume service when you want to proceed to the next 

volume in the set before the end of the current volume (EOV label) is reached 
on input, or before the end-of-tape (EOT) mark is reached on output. VAX 
RMS will then position your process to the first file section on the next 
volume. File sections occur when a file is written on more than one volume, 
the portion of the file on each of the volumes constituting a file section. 

When you perform a Next Volume service for input files, VAX RMS responds 
as follows. 

• If the current volume is the last volume of the set, VAX RMS reports 
end-of-file information. 

• If another file section exists, the next volume is mounted. When necessary, 
the current volume is rewound and a request to mount the next volume is 
issued to the operator. 

• The header label (HDR1) of the file section on the newly mounted volume 
is read. If this is not the volume being sought, the operator is requested to 
mount the correct volume. 

When you perform a Next Volume service for output files, the following 
sequence occurs: 

1 The file section on the current volume is closed with the appropriate 
end-of-volume labels, and the volume is rewound. 

2 The next volume is mounted. 

3 A file with the same file name and the next higher file section number is 
opened for output, and processing continues. 

If your program is operating asynchronously, it must wait for any I/O activity 
on this volume to complete before issuing a Next Volume service. 

The Next Volume service performs a Flush service for write-accessed volumes 
(see $FLUSH), thus writing the I/O buffers on the current volume before 
creating the next file section. If this is an input-only file, then all records 
currently contained in the I/O buffers are lost, and the next Get service will 
return the first record on the next volume. 

The Next Volume service is not supported for DECnet operations for remote 
file access between two VAX/VMS systems. 

Table RMS-28 lists the control block fields read as input and written as 
output by the Next Volume service. For additional information on the fields 
accessed by this service, see Part II. 


Table RMS-28 Next Volume RAB Input and Output Fields 


Use 

Field Name 

Description 

Input 

RAB$W_ISI 

Internal stream identifier (required). 


RAB$L_ROP 

Record-processing option, RAB$V_ASY. 
Asynchronous only: performs Next Volume service 
asynchronously. 

Output 

RAB$I_STS 

Completion status code (also returned in Register 
0). 


RAB$L_STV 

Status value. 
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CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_DNR 

RMSS—NORMAL 

RMS$_STR 

RMS$_SYS 


RMS$_BLN 

RMS$_DPE 

RMS$_PENDING 

RMS$_SUC 


RMS$_CDA 

RMS$_IOP 

RMS$_RAB 

RMS$_SUP 


RMS$_DME 

RMS$_ISI 

RMS$_RSA 

RMS$_SUPPORT 
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$OPEN 

The Open service makes an existing file available for processing by 
your program. The Open service implements the type of access 
desired and determines the degree to which the file can be shared. 
The Open service performs an implicit Display service. 

FORMAT 

SYSSOPEN fab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Open service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Open service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION You must open a file before you perform any record operations and certain 

file operations. If &ny XABs are chained to the FAB, VAX RMS places the 
attribute values in the fields of the appropriate XAB. If you specify a NAM 
block in the FAB, the contents of the device, directory, and file identification 
fields can be used to perform an Open-by-NAM block. In addition, the 
various fields of this NAM block are filled in with auxiliary file specification 
information. 

Table RMS-29 lists the control block fields read as input by the Open service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-29 Open FAB and XAB Input Fields 


Field Name 

Option or 

XAB type 

Description 

FAB$V_CHAN_ 

MODE 3 


Assigns the channel access mode. 

FAB$W_DEQ 


Default file extension quantity: if 
a nonzero value is present in this 
field, it applies only to this open of 
the file. 

FABSI_DNA 


Default file specification string 
address. 

FAB$B_DNS 


Default file specification string size. 

FAB$B_FAC 


File access field. 


FAB$V_BIO 

Block I/O access to a file. 


FAB$V_BRO 

Block or record I/O access to a file. 


FAB$V_DEL 

Delete access to a file. 


FABSV—GET 1 

Read access to a file. 


FAB$V_PUT 

Write access to a file. 


FAB$V_TRN 

Truncate access to a file. 


FAB$V_UPD 

Update access to a file. 

FABSI_FNA 2 


File specification string address. 

FAB$B_FNS 2 


File specification string size. 

FAB$L_FOP 


File-processing options. 


FAB$V_DFW 3 

Deferred write: indicates that 
writing back to file from the 
modified buffer is deferred (applies 
to relative and indexed files only). 


FAB$V_DLT 

Delete: indicates file is to be 
deleted when closed. 


FABSV—NAM 3 

Name block inputs: indicates that 
the NAM$W_FID, NAM$W_DID, 
and NAM$T_DVI fields in the 
specified NAM block are to be 
used to describe the file. 


^his is the default value supplied by VAX RMS. 
2 These fields must be specified by the user. 
3 Not supported for DECnet operations 
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Table RMS-29 (Cont.) Open FAB and XAB Input Fields 


Field Name 

Option or 

XAB tvpe 

Description 


FAB$V_NFS 3 

Non-file-structured: indicates that 
the accessed volume is to be 
processed in a non-file-structured 
manner. 


FAB$V_OFP 

Output file parse: specifies that 
the related file resultant file 
specification string, if used, is 
to provide file name and file type 
defaults only. 


FAB$V_RCK 

Read-check: indicates that transfers 
from disk are to be checked by a 
follow-up, read-compare operation. 


FAB$V_RWC 

Rewind on close (applies to 
magnetic tapes only). 


FAB$V_RWO 

Rewind on open (applies to 
magnetic tapes only). 


FAB$V_SCF 3 

Submit command file: indicates 
that the file is to be submitted as a 
batch-command file to the process 
default batch queue (SYSSBATCH) 
when the file is closed (applies to 
sequential files only). 


FAB$V_SPL 3 

Spool: indicates that the file is to 
be spooled to the process default 
print queue (SYSSPRINT) when the 
file is closed (applies to sequential 
files only). 


FAB$V_SQO 

Sequential only: indicates that 
the file can be processed in a 
sequential manner only. 


FAB$V_TEF 

Truncate at end of file: indicates 
that unused space allocated to a 
file will be deallocated when that 
file is closed (applies to sequential 
files only). 


FAB$V_UF0 3 

User file open: indicates the file 
will be opened only (no further 

VAX RMS processing of that file is 
allowed). 


FAB$V_WCK 

Write-check: indicates that 
transfers to disk are to be followed 
by a read-compare operation. 

FAB$B_FSZ 


Fixed control area size: unit record 
devices only. 

FAB$W_IFI 


Internal file identifier (must be 0). 


3 Not supported for DECnet operations 
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Table RMS-29 (Cont.) Open FAB and XAB Input Fields 


Field Name 

Option or 

XAB type 

Description 

FAB$V_LNM_ 


Specifies the logical name 

MODE 3 


translation access mode. 

FAB$I_NAM 


Name block address. 

FAB$B_RAT 


Record attributes; only for process 
permanent files with print file 
format. 

FAB$B_RFM 


Record format; unit record devices 
only. 

FAB$B_RTV 3 


Retrieval window size. 

FAB$B_SHR 


File sharing field. 


FAB$V_SHRDEL 

Allows other users to delete 
records from the file. 


FAB$V_SHRGET 

Allows other users to read the file. 


FAB$V_MSE 3 

Allows multistream access; also 
used with the FAB$V_MSE and 
FAB$V_GET bits to specify a 
read-only global buffer cache when 
global buffering is enabled. 


FAB$V_NIL 

Prohibits any type of file sharing by 
other users. 


FAB$V_SHRPUT 

Allows other users to write records 
to the file. 


FAB$V_SHRUPD 

Allows other users to update 
records in the file. 


FAB$V_UPI 

Allows one or more users write- 
access to a shared file open for 
block I/O (applies to sequential files 
only). 

FAB$I_XAB 4 


Extended attribute block address. 


3 Not supported for DECnet operations 


4 The appropriate XAB must be specified as input if you desire information about 
that particular XAB on output from the Open Service. 


Table RMS-30 lists the control block fields written as output by the Open 
service. 

Table RMS-30 Open FAB and XAB Output Fields 

Option or 

Field Name XAB Type Description 

FAB$L_ALQ Allocation quantity: contains the highest 

numbered block allocated to the file. 

FAB$B_BKS Bucket size (does not apply to sequential 

files). 
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Table RMS-30 (Cont.) Open FAB and XAB Output Fields 


Field Name 

Option or 

XAB Type 

Description 

FAB$W_BLS 


Device block size (applies only to sequential 
files). 

FAB$W_DEQ 


Default file extension quantity. 

FAB$I_DEV 


Device characteristics. 

FAB$B_FAC 


File access. 

FAB$I_FOP 


File processing options. 


FAB$V_CBT 

Contiguous best try: indicates that the file 
is allocated contiguously on a "best effort" 
basis. 


FAB$V_CTG 

Contiguous: indicates that space for the file 
is allocated contiguously. 


FAB$V_RCK 

Read-check: transfers are followed up by a 
read-compare operation. 


FAB$V_WCK 

Write-check: transfers are followed up by a 
read-compare operation. 

FAB$B_FSZ 


Fixed control area size (applies only to 
variable with fixed length control records). 

FAB$W_GBC 


Global buffer count. 

FAB$W_IFI 


Internal file identifier. 

FAB$I_MRN 


Maximum record number (for relative files 
only). 

FAB$W_MRS 


Maximum record size. 

FAB$B_ORG 


File organization. 

FAB$B_RAT 


Record attributes; used as output field except 
for process permanent files with print file 
format. 

FAB$B_RFM 


Record format. 

FAB$I_SDC 


Spooling device characteristics. 

FAB$B_SHR 


File sharing. 

FAB$I_STS 


Completion status code (also returned in 
Register 0). 

FAB$I_STV 


Status value (contains the I/O channel 
number if the operation is successful). 

FABSl_XAB 


Next XAB address. 


XABALL 

Allocation XAB; see Section 8. 


XABDAT 

Date and time XAB; see Section 9. 


XABFHC 

File header characteristics XAB; 
see Section 10. 


XABKEY 

Key definition XAB; see Section 1 1. 


XABPRO 

Protection XAB; see Section 12. 


XABRDT 

Revision date and time XAB; see Section 13. 


XABSUM 

Summary XAB; see Section 14. 
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Use of the Name Block for Opening Files 

Tables RMS-31 and RMS-32 list the NAM block fields (further described 
in Section 6) that VAX RMS uses as input and output for the Open service 
(provided that the NAM block address field is specified in the FAB). 


Table RMS-31 Open NAM Block Input Fields 


Field Name 

Option 

Description 

NAMSW—DID 1 


Directory identification (input only if 
the FAB$L_FOP field FAB$V_NAM 
option is set). 

NAMST-DVI 1 


Device identification (input only if 
the FAB$I—FOP field FAB$V_NAM 
option is set). 

NAM$I_ESA 


Expanded string area address. 

NAM$B_ESS 


Expanded string area size. 

NAMSW—FID 1 


File identification (input only if the 

FAB$I_FOP field FAB$V_NAM 

option is set). 

NAM$B_NOP 


NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word "password"). 


NAM$V_NOCONCEAL 

Do not conceal device name: 
indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name in the resultant string. 

NAM$I_RLF 


Related file NAM block address. 


NAM$B_RSL 

Related NAM block file resultant 
string length. 


NAM$I_RSA 

Related NAM block file resultant 
string address. 


NAM$I_FNB 

Related NAM block file filename 
status bits. 

NAM$I_RSA 


Resultant string area address. 

NAM$B_RSS 


Resultant string area size. 

1 Not supported for DECnet operations 
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Table RMS-32 Open NAM Block Output Fields 


Field Name 

Description 

NAMSW-DID 1 

Directory identification. 

NAMST—DVI 1 

Device identification. 

NAM$B_ESL 

Expanded string length. (If the NAM$L_ESA and NAM$B_ 

ESS fields are nonzero, and if the FAB$I_FOP field FAB$V_ 

NAM option is clear or the NAM$W_DID and NAM$W_FID 
fields were 0 on input, the expanded file specification string is 
copied to the buffer specified by the NAM$I_ESA field). 

NAMSW-FID 1 

File identification. 

NAM$I_FNB 

File name status bits. 

NAM$B_RSL 

Resultant string length. (If the NAM$L_RSA and NAM$B_ 
RSS fields are both nonzero, and if the FAB$L_FOP field 
FAB$V_NAM option is clear or the NAM$W_FID field was 0 
on input, the resultant file specification is copied to the buffer 
specified by the NAM$I_RSA field). 

1 Not supported for DECnet operations 


The NAM block file specification string descriptors can be used to identify 
individual components of the expanded or resultant file specification. These 
fields include the following: 

• NAM$B_NODE and NAM$L_NODE 

• NAM$B_DEV and NAM$L_DEV 

• NAM$B_DIR and NAM$L_DIR 

• NAM$B_NAME and NAM$L —NAME 

• NAM$B_TYPE and NAM$L_TYPE 

• NAM$B_VER and NAM$L _VER 

For additional information about these descriptors, see Section 6. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACC 

RMS$_ACS 

RMS$_ACT 

RMS$_AID 

RMS$_ATR 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_BUG_DDI 

RMS$_CHN 

RMS$_COD 

RMSS—DEV 

RMS$_DIR 

RMS$_DME 

RMS$_DNA 

R MS$-DNF 

RMS$_DNR 

RMS$_DVI 

RMS$_ENQ 

RMS$_ENV 

RMSS—ESA 

RMS$_ESS 

RMS$_EXP 

RMSS—FAB 

RMS$_FLK 

RMS$_FNA 

RMS$_FNF 

RMS$_FNM 
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RMS$_FOP 

RMS$_IFA 

RMSS—IFI 

RMS$_IMX 

RMSS—IRC 

RMS$_KNM 

RMS$_KSI 

RMS$_LNE 

RMSS—NAM 

RMSS—NET 

RMS$_NETFAIL 

RMS$_NOD 

RMSS—NORMAL 

RMS$_OK_NOP 

RMS$_ORG 

RMS$_PLG 

RMS$_PLV 

RMS$_PRV 

RMSS—QUO 

RMS$_RAT 

RMSS—REF 

RMS$_RLF 

RMS$_RPL 

RMSS—RSS 

RMS$_RST 

RMS$_RUNDOWN 

RMS$_SHR 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPERSEDE 

RMS$_SUPPORT 

RMS$_SYN 

RMS$_SYS 

RMS$_TYP 

RMS$_UPI 

RMS$_VER 

RMSS—WLK 

RMSS—XAB 
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SPARSE 

The Parse service analyzes the file specification string and fills in 
various NAM block fields. 

FORMAT 

SYSSPARSE fab [ f [err][ f sue]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Parse service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Parse service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The functions of the Parse service are performed automatically as part of the 
Open, Create, and Erase services. One special purpose of the Parse service is 
to prepare the FAB and NAM blocks for wildcard character processing to be 
used in the Search service. If wildcard characters, search list logical names, 
or a node name are present in the file specification, VAX RMS allocates 
internal data structures (including a device channel) to store the context 
for subsequent searches. This space is released when the Search service 
encounters a no-more-files condition (in which case an RMS$_NMF error 


RMS-63 












VAX RMS Services 

SPARSE 


status is returned) or when another Parse service is performed using the same 
FAB and NAM blocks. To release this space, use a Parse service that specifies 
the NAM$B_NOP field NAM$V_SYNCHK option and sets the FAB$B_DNS 
and NAM$L_JRLF fields to zero. 

Note that the file must be closed before invoking the Parse service (FAB$W_ 
IFI must be 0). 

By default, the Parse service assigns a channel to the device and does a 
lookup of the directory in addition to analyzing the file specification and 
filling in the NAM block fields. To request a Parse service without I/O, 
specify the NAM$B_NOP field NAM$V_SYNCHK option. The result of 
a Parse service without I/O cannot be used as input to subsequent Search 
services. 

Tables RMS-33 and RMS-34 list the fields in both the FAB and NAM block 
that the Parse service uses as input and output. In addition, the string 
component descriptors are filled in by VAX RMS as output from the expanded 
string (see Section 6). 

The expanded file specification string is moved to the buffer described by 
the expanded string area address (NAM$L_ESA) and size (NAM$B__ESS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_ESA 
and NAM$B_ESS fields must be specified (nonzero) for wildcard character 
processing. 

Table RMS-33 lists the control block fields read as input by the Parse service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-33 Parse FAB and NAM Block Input Fields 


Field Name Option 

FAB$I_DNA 

FAB$B_DNS 

FAB$L_FNA 

FAB$B_FNS 

FAB$L_FOP 


FAB$W_IFI 

FAB$I_NAM 

NAM$L_ESA 

NAM$B_ESS 

NAM$B_NOP 

NAM$V_NOCONCEAL 


Description 

Default file specification string. 

Default file specification string size. 

File specification string address. 

File specification string size. 

File-processing option, FAB$V_OFP. 
Output file parse: indicates that VAX 
RMS uses only the file name and file 
type fields of a related file resultant 
string whose address is contained in 
the NAM$L_RSA field. 

Internal file identifier (must be zero). 
Name block address. 

Expanded string area address. 
Expanded string area size. 

NAM block options. 

Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by the 
actual physical device name in the 
expanded string. 
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Table RMS-33 (Cont.) Parse FAB and NAM Block Input Fields 


Field Name 

Option 

Description 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word "password"). 


NAM$V_SYNCHK 

Performs Parse service with no I/O. 

NAM$I_RLF 


Related file NAM block address. 


NAM$I_RSA 

Related file NAM block resultant string 
area address. 


NAM$B_RSL 

Related file NAM block resultant string 
length. 


NAM$L_FNB 

Related file NAM block filename status 
bits. 


Table RMS-34 lists the control block fields written as output by the Parse 
service. 


Table RMS-34 Parse FAB and NAM Block Output Fields 


Field Name Description 


FAB$L_DEV 

Device characteristics (not if the NAM$B_NOP field NAM$V_ 
SYNCHK option is set). 

FAB$I_SDC 

Secondary device characteristics (not if the NAM$B_NOP field 
NAM$V_SYNCHK option is set). 

FAB$L_STS 

Completion status code (also returned in Register 0). 

FAB$I_STV 

Status value. 

NAMSW-DID 1 

Directory identification (not if the NAM$B_NOP field NAM$V_ 
SYNCHK option is set). 

NAMST-DVI 1 

Device identification (not if the NAM$B_NOP field NAM$V_ 
SYNCHK option is set). 

NAM$B_ESL 

Expanded string length. 

NAMSW—FID 1 

File identification (zeroed). 

NAMSI_FNB 

File name status bits: contains information about the parse 
results. 

NAM$L_WCC 

Wildcard context. 


^ot supported for DECnet operations. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 
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RMS$_ACS 

RMS$_CHN 

RMS$_DNA 

RMS$_ESS 

RMS$_IFI 

RMS$_NORMAL 

RMSS—STR 

RMS$_VER 


RMS$_BLN 

RMS$_BUG_DDI 

RMS$_DEV 

RMS$_DIR 

RMS$_DNF 

RMS$_DNR 

RMSS—FAB 

RMSS—FNA 

RMSS—LNE 

RMSS—NAM 

RMS$_QUO 

RMS$_RLF 

RMS$_SUC 

RMS$_WCC 

RMS$_SYN 



RMS$_CDA 

RMS$_DME 

RMS$_ESA 

RMS$_FNM 

RMSS—NOD 

RMS$_RUNDOWN 

RMS$_TYP 
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$PUT 

The Put service inserts a record into a file. 

FORMAT 

SYSSPUT rab [,[err][,sue]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Put service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Put service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

New records placed in a file by the Put service are inserted either at the 
end of sequential and relative files or in empty record cells in place of 
deleted records in relative files. Location of new records in an indexed file 
is controlled by VAX RMS, which examines the contents of the primary key 
field of the record to determine where to insert the record into the file. 
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Inserting Records into Sequential Files 

When using the sequential record access mode to process sequential files, you 
usually insert records at the end of the file only. The records to be inserted 
cannot be larger than the maximum length you specified when the file was 
, created. You can use the random-by-key (relative record number) access 
mode and the update-if record-processing option (RAB$V_UIF bit set in the 
RAB$L_ROP field) to insert fixed-length records into a sequential file residing 
on a disk device. 

The truncate-on-put option (RAB$V__TPT bit set in the RAB$L_ROP field) 
may be specified for sequential files. This option allows new records to be 
inserted into existing files, in locations other than at the end of file. When 
the record is inserted, the file is truncated automatically to a new end of 
the file, immediately after the record is inserted, regardless of whether data 
had existed after that point. If truncate access to the file is not enabled, the 
operation will be rejected with a file access error (RMS$_FAC). 

For stream format files, VAX RMS writes the contents of the user's buffer 
into the file at the current byte position. If the last byte is not a terminator, 
a terminator will be added. For STM format, the terminator CR (carriage 
return) followed by LF (line feed) is added. 

Mailboxes may be used to synchronize activity across cooperating processes. 
Usually, a Put service to a mailbox will not be completed until another 
accessor to the mailbox reads the record. When the Put service is completed, 
the RAB$L_STV field will contain the process identification (PID) of the 
process that read the record. If the timeout (RAB$V_TMO) RAB$L_ROP 
option is specified with a timeout period of 0, the Put service will not wait for 
another accessor to read the record. 

Inserting Records into Relative Files 

When processing relative files, you can use either sequential or random-by¬ 
key record access mode. Records cannot be larger than the size specified at 
file creation time, and the record's relative record number must not exceed 
the maximum record number established for the file. Usually, if the target 
record cell for a Put service contains a record, a record-already-exists error 
(RMS$_REX) will be returned as the completion status (RAB$L_STS). If you 
specify the update-if (RAB$V_UIF) record option, however, VAX RMS will 
overwrite the existing record, instead of returning an error message. Update 
access is required to the file or else the operation will be rejected with a file 
access error (RMS$_FAC). 

Inserting Records into Indexed Files 

In an indexed file, you can use either the sequential or the random-by-key 
record access mode. When sequential access is used to insert records, the 
primary key value of the record to be inserted must be consistent with the 
specified sort order of the file. That is, the key must be greater than or equal 
to the primary value of the previous record if ascending sort order is specified; 
but if descending sort order is specified, it must be less than or equal to the 
primary key value of the previous record. 

The records cannot be larger than the size established when the file was 
created if a maximum length was specified. Each record written must contain 
a complete primary key, but the records do not have to contain all alternate 
keys. If alternate keys are partially or completely missing because of record 
length, VAX RMS will not make an entry for that new record in the associated 
alternate index. Put services to an indexed file do not require a separate key 
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value or key of reference. By examining the contents of the primary key in 
the record, VAX RMS determines where to insert the record. 

When inserting a record into an indexed file, VAX RMS compares the key 
values in the record with the key values of records previously inserted into 
the file to determine whether or not the record key value duplicates any 
existing key values. If the record duplicates a key value in an index where 
duplication is not allowed, VAX RMS rejects the operation with an RMS$_ 
DUP error code. Where duplicate keys are allowed, VAX RMS inserts the 
record. 

Records with duplicate keys are inserted in chronological order; that is, VAX 
RMS inserts each record having duplicate keys at the end of a "chain" of 
identically keyed records so that newer records are stored closer to the end of 
the file regardless of sort order. 

If you specify the update-if (RAB$V_UIF) RAB$L__ROP option when 
duplicates are not allowed on the primary key, VAX RMS will simply 
overwrite an existing record with the same primary key value, rather than 
returning a duplicate record error (RMS$_DUP). Alternate key values will be 
modified to reflect the newly inserted record. It will appear as if an Update 
service is being performed on the existing record. When the RAB$V_UIF 
option is used, update access to the file is required. If update access is not 
permitted for the file, then a Put service (which becomes an Update service 
when this option is selected) will fail, and a file access error (RMS$_FAC) will 
be returned. 

Be careful when invoking the PUT service with the RAB$V_UIF option and 
automatic record locking for a shared file. The Put service, unlike the Update 
service, momentarily releases record locks previously applied by a Get or 
Find service, until the PUT service is converted into an Update service. This 
could allow another record stream to delete or update the record between the 
invocation of the Put service and the conversion to an Update service. To 
avoid this complication, you should use the Update service instead of the Put 
service with the update-if option to update an existing record in a file sharing 
situation. 

The record address (RAB$L_RBF) and record size (RAB$W_RSZ) are required 
for all Put services. Some options for the Put services, however, require 
additional fields. Following the completion of a successful Put service, the 
record's file address (RFA) is always returned in the RAB$W_RFA field. 

Table RMS-35 lists the control block fields read as input by the Put service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-35 Put RAB Input Fields 


Field Name 

Option or 
XAB Type 

Description 

RAB$W_ISI 


Internal stream identifier (required). 

RAB$L_KBF 


Key buffer address (used only if RAB$B_ 
RAC is KEY and the file is a relative file). 

RAB$B_KSZ 


Key size (used only if RAB$B_RAC is KEY 
and the file is a relative file). 

RAB$B_RAC 


Record access mode (SEQ, KEY) 1 . 


^he default for the RAB$B_RAC field is RAB$C_SEQ. 
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Table RMS—35 (Cont.) Put RAB Input Fields 


Field Name 

Option or 

XAB Type 

Description 

RABSl_RBF 


Record buffer address. 

RAB$I_RHB 


Record header buffer (applies only to 
variable with fixed control records). 

RAB$W_RSZ 


Record size. 

RABSL _ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Put services 
asynchronously. 


RAB$V_CC0 2 

Cancel CTRL/O: guarantees that terminal 
output will not be discarded if the operator 
has entered CTRL/O. 


RAB$V_LOA 

Load: specifies that buckets are to be 
loaded according to the fill size established 
at file creation time. 


RAB$V_RLK 

Read of locked record allowed: specifies 
that a user who locks a record is permitting 
the locked record to be read by other 
accessors. 


RAB$V_TM0 2 

Timeout: indicates that the content of the 
timeout period (RAB$B_TMO) field of is to 
be used. 


RAB$V_TPT 

Truncate-on-put: specifies that a Put 
service with a record accessed sequentially 
can occur at any point in the file, truncating 
the file at that point. 


RAB$V_UIF 

Update-if: converts a Put service to a 
record that already exists to an Update 
service. 


RAB$V_WBH 

Write behind: two buffers are allocated to 
allow multibuffering. 

RAB$B_TM0 2 


Timeout period: a value of zero indicates 
that VAX RMS should not wait to complete 
a Put service (applies to mailbox devices 
only). 

2 Not supported for DECnet operations 


Table RMS-36 lists the control block fields written as output by the Put 
service. 
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Table RMS-36 Put RAB Output Fields 


Field Name 

Option or 
XAB Type 

Description 

RAB$I_BKT 


Bucket code: set to the relative record number 
for sequential access to relative files. 

RAB$W_RFA 


Record's file address. 

RAB$L_STS 


Completion status code (also returned in 

Register 0). 

RAB$L_STV 


Status value 1 . 

the successful completion of a Put service to a record-oriented device, the 

RAB$I_STV field will contain the second longword of the I/O status block. 

See the VAX/VMS I/O User's Reference Manual: Part 1 in the VAX/VMS I/O 
Reference Volume for details on specific devices. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMSS—ACT 

RMS$_BUG_DAP 

RMS$_CONTROLC 

RMS$_DME 

RMS$_ENQ 

RMS$_FTM 

RMSS—IDX 

RMS$_ISI 

RMS$_KSZ 

RMS$_NET 

RMSS—OK _ALK 

RMSS-PENDING 

RMS$_RAC 

RMS$_REX 

RMS$_RPL 

RMSS—RSZ 

RMS$_SQO 

RMS$_SUP 

RMS$_TRE 

RMSS—WLK 


RMS$_BLN 

RMS$_CDA 

RMS$_CONTROLO 

RMS$_DNR 

RMS$_EXT 

RMS$_FUL 

RMS$_IOP 

RMS$_KBF 

RMS$_MRN 

RMS$_NETFAIL 

RMS$_OK_DUP 

RMS$_PLG 

RMS$_RBF 

RMS$_RHB 

RMSS—RRV 

RMS$_RVU 

RMS$_STR 

RMS$_SUPPORT 

RMS$_WBE 

RMS$_WPL 


RMSS—BUG 

RMS$_CHK 

RMSS—CONTROLY 

RMS$_DUP 

RMS$_FAC 

RMS$_IBF 

RMS$_IRC 

RMS$_KEY 

RMS$_NEF 

RMS$_NORMAL 

RMS$_OK_IDX 

RMS$_RAB 

RMS$_RER 

RMS$_RLK 

RMS$_RSA 

RMS$_SEQ 

RMS$_SUC 

RMS$_SYS 

RMS$_WER 
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$READ 

The Read service retrieves a specified number of bytes from a file 
(beginning on a block boundary) and transfers them to memory. 

A Read service using block I/O can be performed on any file 
organization. 

FORMAT 

SYSSREAD rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Read service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Read service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION To use the Read service, you must do the following: 

1 Supply a buffer area into which VAX RMS is to transfer data (user record 
area address field, RAB$L_UBF) 

2 Indicate the number of bytes to be transferred (user record area size field, 
RAB$W_USZ) 

3 Indicate the first virtual block number (VBN) for the transfer (bucket 
number field, RAB$L_BKT). If the value for the VBN is 0, the transfer will 
start with the block indicated by the NBP (Next Block Pointer). 

Table RMS-37 lists the control block fields read as input by the Read service. 

For additional information on the fields accessed by this service, see Part II. 


Table RMS-37 Read RAB Input Fields 


Field Name 

Description 

RAB$L_BKT 

Bucket number: must contain the virtual block number of the 
first block to read. When this field has a value of 0, then the 
next block is read. 

RAB$W_ISI 

Internal stream identifier. 

RAB$I_ROP 

Record-processing option, ASY (RAB$V_ASY). Asynchronous: 
performs Read services asynchronously. 

RAB$I_UBF 

User record area address. 

RAB$W_USZ 

User record area size: indicates the length of transfer, in bytes 1 

Certain devices require that an even number of bytes be transferred. For further 
details, see the VAX/VMS I/O User's Reference Manual: Part 1 in the VAX/VMS 
I/O Reference Volume. 

Table RMS-38 lists the control block fields written as output by the Read 
service. 

Table RMS- 

-38 Read RAB Output Fields 

Field Name 

Description 

RAB$I_RBF 

Record address. 

RAB$W_RFA 

Record's file address: contains the virtual block number of the 
first block transferred. 

RAB$W_RSZ 

Record size: indicates the actual number of bytes transferred. 

RAB$I_STS 

Completion status code (also returned in Register 0). 

RAB$I_STV 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS-73 
















VAX RMS Services 

$READ 


RMS$_ACT 

RMS$_BLN 

RMS$_BUG_DAP 

RMS$_CDA 

RMS$_CONTROLC 

RMS$_CONTROLY 

RMS$_DME 

RMS$_DNR 

RMS$_EOF 

RMS$_FAC 

RMSS—FTM 

RMS$_IOP 

RMSS—ISI 

RMS$_NET 

RMSS—NETFAIL 

RMS$_ 

NORMAL 

RMS$_PBF 

RMS$_PENDING 

RMS$_RAB 

RMS$_RER 

RMSS—RSA 

RMS$_STR 

RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 

RMS$_TMO 

RMS$_UBF 

RMS$_USZ 

RMS$_WBE 
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$RELEASE 



The Release service unlocks the record specified by the contents of 
the record's file address (RAB$W_RFA) field of the RAB. 

FORMAT 

SYSSRELEASE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Release service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Release service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Release service unlocks a specified record (see also the discussion of the 
Free service). If the named record is not locked, VAX RMS returns a status 
code of RMS$_RNL. 
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Table RMS-39 lists the control block fields read as input and written as 
output by the Release service. For additional information on the fields 
accessed by this service, see Part II. 


Table RMS-39 Release RAB Input and Output Fields 


Use 

Field 

Name 

Description 

Input 

RABSW—ISI 

Internal stream identifier (required). 


RAB$W_RFA 

Record's file address (required). 

Output 

RAB$I_STS 

Completion status code (also returned in Register 0). 


RAB$I_STV 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_ISI 

RMS$_PENDING 

RMS$_STR 


RMSS—BLN 

RMS$_NET 

RMS$_RAB 

RMS$_SUC 


RMS$_BUG_DAP 

RMS$_NETFAIL 

RMS$_RNL 

RMS$_SUP 


RMS$_CDA 

RMS$_NORMAL 

RMS$_RSA 

RMS$_SUPPORT 
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$REMOVE 



The Remove service deletes a file name from a directory. It is the 
reverse of the Enter service. 

FORMAT 

SYSSREMOVE fab [ f [err][ f sue]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for 
the Remove service call. The fab argument is the address of the FAB control 
block. 

err 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Remove service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Remove service searches for the first file name that matches the expanded 
name string and directory ID in the user's NAM block, and then it deletes 
the file name without deleting the actual file. The Remove service is similar 
to the Erase service, except that the Erase service also deletes the file after 
performing an implicit Remove. Note that the file must be closed before 
invoking the Remove service (that is, the value of FAB$W_IFI must be 0). 
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The Remove service accepts wildcard characters and search lists, and it 
is usually preceded by a call to the Parse service in order to fill in the 
appropriate fields of the NAM block. Because the Remove service returns 
the wildcard context field of the NAM block (NAM$L_JWCC), the Remove 
service can be used on multiple successive calls in order to remove successive 
file names that match a wildcard file specification. 

Be careful when you mix calls to the Search and Remove services. For 
example, assume you invoke the following service sequence: 

• PARSE 

• SEARCH 

• REMOVE 

• SEARCH 

• REMOVE 

VAX RMS will respond by doing the following: 

1 Search for the first file specification that matches the expanded name 
string 

2 Search for and remove the second file specification 

3 Search for the third file specification 

4 Search for and remove the fourth file specification 

If you want to remove the directory entry of a file and you have that file's 
ID, then you can improve the speed of the Remove service by specifying the 
NAM bit in the FAB$L_FOP field. In order to do this properly, you must first 
parse the name of the file specification (to clear the NAM$W__FID field), place 
the correct FID in the NAM block, and then perform the Remove service. 

The Remove service is not supported for DECnet operations for remote file 
access between two VAX/VMS systems. 

Table RMS-40 lists the control block fields read as input by the Remove 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-40 Remove FAB and NAM Block Input Fields 


Field Name 

Description 

FAB$I_FOP 1 

File-processing option, FAB$V_NAM only. NAM block inputs: 
indicates that the NAM$W_FID field will be used as input. 

FAB$W_IFI 

Internal file identifier (must be zero). 

FAB$I_NAM 

Name block address. 

NAMSW—DID 1 

Directory identification; contains identification of directory 
cataloging file to be removed. 

NAMST—DVI 1 

Device identification; contains identification of device 
containing directory from which file is to be removed. 

NAM$I_ESA 

Expanded string area address specifying the name, type, and 
version of file to be removed. 


1 Not supported for DECnet operations 
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Table RMS-40 (Cont.) Remove FAB and NAM Block Input 

Fields 


Field Name 

Description 

NAM$B_ESL 

Expanded string length. 

NAMSW—FID 1 

File identification: if nonzero and FAB$L_FOP field FAB$V_ 
NAM bit is set in the input FAB, the first file in the directory 
with this file identification is removed. 

NAM$L_FNB 

File name status bits (wildcard character bits only). 

NAM$I_RSA 

Resultant string area address: specifies the name, type, and 
version number of last file removed (required for wildcard 
character processing). 

NAM$B_RSL 

Resultant string length. 

NAM$B_RSS 

Resultant string area size. 

NAM$I_WCC 

Wildcard character context value. 


1 Not supported for DECnet operations 


Table RMS-41 lists the control block fields written as output by the Remove 
service. 


Table RMS- 

-41 Remove FAB and NAM Block Output Fields 

Field Name 

Description 

FABSl_STS 

Completion status code (also returned in Register 0). 

FAB$I_STV 

Status value. 

NAM$B_RSL 

Resultant string length. 

NAM$I_WCC 

Wildcard context value. 


The resultant string is moved to the buffer described by the NAM$L_RSA 
and NAM$B_RSS fields (only if both fields are nonzero on input). 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_BLN 

RMS$_DME 

RMS$_ESA 

RMSS—IFI 

RMSS—PRV 

RMS$_RST 

RMS$_SUPPORT 

RMS$_WLK 


RMS$_CDA 

RMSS—DNF 

RMS$_ESL 

RMS$_NAM 

RMS$_RMV 

RMS$_STR 

RMSS—SYS 


RMS$_CHN 

RMS$_DNR 

RMS$_FAB 

RMS$_NMF 

RMS$_RSL 

RMS$_SUC 

RMS$_WCC 


RMS$_DEV 

RMSS—DVI 

RMS$_FNF 

RMS$_NORMAL 

RMS$_RSS 

RMS$_SUP 

RMSS—WLD 
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$REIMAME 



You can use this service to change the name, type, or version of a 
file, or to move a file to another directory by changing its directory 
specification. However, note that you cannot use this service to 
move a file to another device. 

FORMAT 

SYSSRENAME old-fab[,[err][,suc]],new-fab 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

old-fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Rename service call. The old-fab argument is the address of the FAB control 
block that specifies the old file name. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Rename service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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new-fab 


VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

The new-fab argument is the address of the FAB control block that specifies 
the new file name. 


Note: If you invoke the Rename service using the $RENAME macro and if 
you do not specify arguments, you must construct an additional field 
within your argument list to contain the address of the FAB that specifies 
the new file name. This additional field is placed in the argument list 
following the field for the success completion routine (see Part I), and the 
argument count is set to 4. 


DESCRIPTION The Rename service performs the equivalent of two Parse services (old and 

new name), a Search service for the old directory, an Enter service to insert 
the new file name into the new directory, and a Remove service to delete the 
old file name from the old directory. 

Note that the file must be closed before invoking the Rename service 
(FAB$W_IFI must be 0), and no wildcard character specifications are allowed. 
You can move a file from one directory to another using this service, but both 
directories must be on the same disk device. 

If the Rename service is successful, the new directory entry is created and the 
old entry is deleted. If the service fails, the old entry remains and the new 
entry is deleted. 

Table RMS-42 lists the fields in two FABs and two NAM blocks that the 
Rename service uses as input and output. In the table, these blocks are 
called FAB#1 and NAM#1 for the old entry, and FAB#2 and NAM#2 for the 
new entry. For output, FAB#2 is not used, although it must be in writeable 
memory. To check or signal the completion codes in FAB$L_STS and 
FAB$L _STV, use the first FAB (FAB#1). 

The resultant file specification string for each of the names (old and new) is 
placed in the buffer described by the NAM$L_RSA and NAM$B_RSS fields 
of the separate NAM blocks (only if both fields are nonzero). 

Table RMS-42 lists the control block fields read as input by the Rename 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS—42 Rename FAB and NAM Block Input Fields 


Control 

Block 

FAB# 1 

and 

FAB#2 


Field 

Name Description 

FAB$L_DNA Default file specification string address. 


FAB$B_DNS Default file specification string size. 

FAB$L_FNA File specification string address. 

FAB$B_FNS File specification string size. 
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Table RMS-42 (Cont.) Rename FAB and NAM Block Input 

Fields 


Control 

Block 

Field 

Name 

Description 


FAB$W_IFI 

Internal file identifier (must be zero). 


FAB$I_NAM 

Name block address. 

NAM# 1 

NAM$L_ESA 

Expanded string area address (must be nonzero). 

and 

NAM#2 


NAM$B_ESS 

Expanded string area size (must be nonzero). 


NAM$I_RLF 

Related file NAM block address. 


NAM$L_RSA 

Resultant string area address. 


NAM$B_RSS 

Resultant string area size. 

Related 

NAM$L_RSA 

Related file resultant string area address. 

file 

NAM 

NAM$B_RSL 

Related file resultant string length. 

blocks 


NAM$I_FNB 

Related file name status bits. 

Table RMS- 

-43 lists the control block fields written as output by the Rename 

service. 

Table RMS-43 Rename FAB and NAM Block Output Fields 

Control 

Field 


Block 

Name 

Description 

FAB# 1 

FAB$L_STS 

Completion status code (also returned in 
Register 0). 


FAB$L_STV 

Status value. 

NAM#1 

NAMSW—DID 1 

Directory identification. 

and 

NAM#2 


NAM$T_DVl’ 

Device identification. 


NAM$B_ESL 

Expanded string length. 


NAMSW—FID 1 

File identification. 


NAM$I_FNB 

File name status bits. 


NAM$B_RSL 

Resultant string length. 


NAM$I_WCC 

Wildcard context. 

^ot supported for DECnet operations 
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CONDITION 


VALUES 

RETURNED 

The following condition values are described in Appendix A: 

RMS$_ACC 

RMS$_BLN 

RMS$_BUG_DDI 

RMS$_CDA 


RMS$_CHN 

RMS$_DEV 

RMS$_DIR 

RMS$_DME 


RMSS—DNA 

RMS$_DNF 

RMS$_DNR 

RMS$_DVI 


RMSS—ENT 

RMS$_ESA 

RMS$_ESS 

RMS$_FAB 


RMS$_FNA 

RMSS—FNM 

RMS$_IDR 

RMS$_IFI 


RMS$_LNE 

RMS$_NAM 

RMS$_NET 

RMS$_NETFAIL 


RMS$_NMF 

RMS$_NORMAL 

RMS$_PRV 

RMS$_QUO 


RMS$_REENT 

RMSS—RLF 

RMS$_RMV 

RMS$_RSS 


RMS$_RST 

RMS$_RUNDOWN 

RMS$_STR 

RMS$_SUC 


RMS$_SUPPORT 

RMS$_VER 

RMS$_SYN 

RMS$_WLD 

RMS$_SYS 

RMS$_TYP 
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SREWIND 

The Rewind service sets the context of a record stream to the first 
record in the file. VAX RMS alters the context of the next record to 
indicate the first record as being the next record. 

FORMAT 

SYSSREWIND rab[,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Rewind service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Rewind service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION The Rewind service implicitly performs the Flush and Free services, writing 
out all I/O buffers and releasing all locked records. This service is valid for 
all file organizations on disk volumes and for sequential files on tape volumes. 
For indexed files, the key of reference field establishes the index to be used 
for subsequent sequential accesses. You cannot rewind a unit record device, 
such as a card reader, a mailbox, a printer, or a terminal. You cannot rewind 
indirectly accessed process-permanent files. Also, you cannot rewind a file 
that was opened with the FAB$L_FOP field FAB$V_SQO option set. 

Table RMS-44 lists the control block fields read as input by the Rewind 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-44 Rewind RAB Input Fields 


Field Name 


Description 


RAB$W_ISI 

RAB$B_KRF 

RAB$L_ROP 


Internal stream identifier (required). 

Key of reference (used only with indexed files). 

Record-processing option, RAB$V_ASY option only. 
Asynchronous: performs a Rewind service asynchronously. 


Table RMS-45 lists the control block fields written as output by the Rewind 
service. 


Table RMS-45 Rewind RAB Output Fields 


Field Name 

Description 


RAB$I_STS 

RAB$I_STV 

Completion status code (also returned in Register 0). 

Status value. 



CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BOF 

RMS$_DNR 

RMSS—KRF 

RMS$_PENDING 

RMSS—STR 

RMSS—SYS 


RMS$_ATR 

RMS$_BUG_DAP 

RMS$_DPE 

RMS$_NET 

RMS$_QUO 

RMS$_SUC 

RMS$_WBE 


RMS$_ATW 

RMS$_CDA 

RMS$_IOP 

RMS$_NETFAIL 

RMS$_RAB 

RMS$_SUP 

RMS$_WER 


RMS$_BLN 

RMS$_DME 

RMS$_ISI 

RMS$_NORMAL 

RMS$_RSA 

RMS$_SUPPORT 

RMSS—WLK 
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$SEARCH 

The Search service scans a directory file and fills in various NAM 
block fields. This service should be preceded by the Parse service, 
in order to initialize the NAM block appropriately. 

FORMAT 

SYSSSEARCH fab [ f [err] [ f sue]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 

ARGUMENTS 

fab 

VMS Usage: fab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

FAB control block whose contents are to be used as indirect arguments for the 
Search service call. The fab argument is the address of the FAB control block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Search service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The basic functions of the Search service and the Parse service are performed 
automatically as part of the Open, Create, and Erase services. Note that the 
file must be closed before invoking the Search service (FAB$W_IFI must be 

0). 
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When called, the Search service scans the directory file specified by the 
directory identification (NAM$W_DID) field of the NAM block. It looks for 
an entry that matches the file name, type, and version number specified by 
the expanded string area address and expanded string length fields. Upon 
finding a match, VAX RMS returns the file name, type, and version number 
in the buffer described by the resultant string area address and size fields, 
and the file identification field is filled in, thereby allowing a subsequent 
Open-by-NAM block operation. You can use the Search service to return a 
series of file specifications, whose names match a given file specification that 
contains wildcard characters or search lists. 

Table RMS-46 lists the fields in both the FAB and NAM block that the 
Search service uses as input and output. In addition, the string component 
descriptors are filled in by VAX RMS as output from the resultant string 
(see Section 6). 

The resultant file specification string is placed in the buffer described by 
the resultant string area address (NAM$L_RSA) and size (NAM$B_RSS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_RSA 
and NAM$B_RSS fields must be specified (nonzero) for wildcard character 
processing. 

Table RMS-46 lists the control block fields read as input by the Search 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-46 Search FAB and NAM Block Input Fields 


Field Name 

Option 

Description 

FAB$W_IFI 


Internal file identifier (must be zero). 

FAB$I_NAM 


Name block address. 

NAMSW-DID 1 


Directory identification of the 
directory to be searched. 

NAMST—DVI 1 


Device identification of device 
containing directory to be searched. 

NAMSl_ESA 


Expanded string area address: 
specifies file name, type, and version 
of file. 

NAM$B_ESL 


Expanded string length. 

NAMSl_FNB 


File name status bits (wildcard 
characer options only). 

NAM$B_NOP 


NAM block options. 


NAM$V_PWD 

Password: indicates that a password 
contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word "password"). 


^ot supported for DECnet operations 
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Table RMS-46 (Cont.) Search FAB and IMAM Block Input Fields 


Field Name 

Option 

Description 


NAM$V_NOCONCEAL 

Do not conceal device name: 
indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name in the resultant string. 


NAM$V_SRCHXABS 

Performs Display service on 
remote files (for output fields, see 
description of Display service). 

NAM$I_RSA 


Resultant NAM block string area 
address: specifies name, type, and 
version of last file found (required for 
wildcard character processing). 

NAM$B_RSL 


Resultant NAM block string length. 

NAMSB—RSS 


Resultant NAM block string area 
size. 

NAM$I_WCC 


Wildcard character context value. 


Table RMS-47 lists the control block fields written as output by the Search 
service. 


Table RMS-47 Search FAB and NAM Block Output Fields 


Field Name 

Description 

FAB$L_STS 

Completion status code (also returned in Register 0). 

FAB$L_STV 

Status value. 

NAMSW-FID 1 

File identification. 

NAM$L_FNB 

File name status bits (wild directory bits only). 

NAM$B_RSL 

Resultant string length. 

NAM$I_WCC 

Wildcard character context value. 

1 Not supported for DECnet operations 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACS 

RMS$_DME 

RMS$_ESA 

RMS$_FNF 

RMS$_NETFAIL 

RMS$_PRV 


RMS$_BLN 

RMS$_DNF 

RMS$_ESL 

RMS$_IFI 

RMS$_NMF 

RMS$_RSL 


RMS$_CHN 

RMS$_DNR 

RMSS—FAB 

RMS$_NAM 

RMS$_NORMAL 

RMS$_RSS 


RMS$_DEV 

RMS$_DVI 

RMS$_FND 

RMS$_NET 

RMS$_NOV ALPRS 

RMS$_RST 
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RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 

RMS$_SYS RMSS—WCC 
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$SPACE 

The Space service lets you position a file forward or backward a 
specified number of blocks. 

FORMAT 

SYSSSPACE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L__STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Space service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Space service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The Space service is intended primarily for use with magnetic tape files; the 
tape is spaced the number of blocks specified in the bucket number field. 

(The size of each block on any tape is specific to that tape and is defined on 
the tape itself, not by VAX/VMS or VAX RMS.) If the value in this field is 
positive, the tape spaces forward; if the value is negative, the tape spaces 
backward. For disk files, the next block pointer (NBP) is updated to reflect 
the new sequential operation position. 
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Table RMS-48 lists the control block fields read as input by the Space service. 
For additional information on the fields accessed by this service, see Part II. 

Table RMS-48 Space RAB Input Fields 


Field Name 

Description 

RAB$L_BKT 

RAB$W_ISI 

RAB$I_ROP 

Bucket code: indicates the number of blocks to space forward 
(positive value) or backward (negative value). 

Internal stream identifier. 

Record-processing option, RAB$V_ASY only. Asynchronous: 
performs Space services asynchronously. 

Table RMS-49 lists the control block fields written as output by the Space 
service. 

Table RMS- 

-49 Space RAB Output Fields 

Field Name 

Description 

RAB$I_STS 

RAB$I_STV 

Completion status code (also returned in Register 0). 

Status value (set to number of blocks actually spaced; the value 
is always positive). 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMSS—ACT 

RMS$_CDA 

RMS$_EOF 

RMS$_NETFAIL 

RMS$_RSA 

RMS$_SUPPORT 


RMS$_BLN 

RMS$_DME 

RMS$_IOP 

RMS$_NORMAL 

RMSS—STR 

RMS$_SYS 


RMS$_BOF 

RMS$_DNR 

RMS$_ISI 

RMS$_PENDING 

RMS$_SUC 

RMS$_WBE 


RMS$_BUG_DAP 

RMS$_DPE 

RMS$_NET 

RMS$_RAB 

RMS$_SUP 
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SYS$RMSRUNDWN 


SYS$RMSRUNDWIM 

The description of the I/O rundown control routine service has been 
relocated in the VAX/VMS System Services Reference Manual. 
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SYS$SETDDIR 


SYS$SETDDIR 

The description of the default directory control routine has been 
relocated in the VAX/VMS System Services Reference Manual. 
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SYS$SETDFPROT 


SYS$SETDFPROT 

The description of the default file protection control routine has been 
relocated in the VAX/VMS System Services Reference Manual. 
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$TRUNCATE 

The Truncate service removes records from the end of a sequential 
file. 


FORMAT 

SYSSTRUNCATE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Truncate service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast—procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Truncate service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

You can only use the Truncate service to truncate a sequential file; the file 
must be open for exclusive access. (The file-sharing (FAB$B_SHR) field must 
be set or defaulted to NIL.) The file access (FAB$B_FAC) field must specify 
truncate access (FAB$V_TRN). 
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The Truncate service deletes the record indicated as the current record, and all 
following records. You can use this service only immediately after successful 
execution of a Get or Find service (thereby setting the context of the current 
record). 

VAX RMS declares an end of file at the starting record position for the 
truncation and then causes the context of the next record to be set to this end 
of file. You can then add records to the file by issuing successive Put services. 

Table RMS-50 lists the control block fields read as input by the Truncate 
service. For additional information on the fields accessed by this service, 
see Part II. 

Table RMS-50 Truncate RAB Input Fields 

Field Name Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$L_ROP Record-processing option, RAB$V_ASY only. Asynchronous: 

performs Truncate services asynchronously. 


Table RMS-51 lists the control block fields written as output by the Truncate 
service. 


Table RMS-51 Truncate RAB Output Fields 


Field Name 

Description 

RAB$I_STS 

RAB$L_STV 

Completion status code (also returned in Register 0). 

Status value. 


CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 


RMS$_ACT 

RMS$_BUG_DAP 

RMSS—DME 

RMS$_IOP 

RMSS—NORMAL 

RMS$_RSA 

RMS$_SUPPORT 

RMS$_WLK 


RMSS—ATR 

RMSS—CDA 

RMS$_DNR 

RMS$_ISI 

RMSS—PENDING 

RMS$_STR 

RMS$_SYS 


RMS$_ATW 

RMS$_CUR 

RMS$_DPE 

RMS$_NET 

RMS$_RAB 

RMS$_SUC 

RMS$_WBE 


RMS$_BLN 

RMS$_DEADLOCK 

RMSS—FAC 

RMS$_NETFAIL 

RMSS—RER 

RMS$_SUP 

RMSS—WER 
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$UPDATE 

The Update service allows you to modify the contents of an existing 
record in a file residing on a disk device. 

FORMAT 

SYSSUPDATE rab [,[err][,suc]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Update service call. The rab argument is the address of the RAB control 
block. 

err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 

sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Update service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 

DESCRIPTION 

The record to be updated by the Update service must first be locked by this 
stream, using either a Find or Get service. When updating a record, you must 
use move mode (not locate mode); that is, you must supply a buffer. 
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The record length for sequential files cannot change. For relative files with 
variable-length or variable with fixed-length control records, the length of the 
replacement record can be different from the length of the original record, but 
cannot be larger than the maximum size you set when you created the file. 

For stream format files, the Update service functions in the same manner as 
the Put service, with one exception. When using the Update service, you do 
not have to set the RAB$L_ROP field RAB$V_TPT option to update data in 
the middle of a file. 

For indexed files, the length of the replacement record written by the Update 
service may be different from the original record. Each replacement record 
must be large enough to contain a complete primary key, but it does not have 
to contain all alternate keys. If an alternate key is partially or completely 
missing in the replacement record, the key must have the characteristic that 
the values can change; this is also true if the replacement record contains a 
key that was not present in the original record. 

Update operations to an indexed file do not require a key value or key of 
reference. Before writing the record, VAX RMS compares the key values 
(primary and alternate) in the replacement record with the key values of the 
original record already existing in the file. This comparison takes the defined 
characteristics of each key into account. For example, if a particular key is not 
allowed to change, VAX RMS rejects the operation with an RMS$_CHG error 
code if the replacement record contains an altered value in the associated key. 
Similarly, this comparison determines whether the replacement record would 
result in the presence of duplicate key values among records of the file. If 
duplicates would occur, VAX RMS verifies the defined characteristics for the 
keys being duplicated. If duplicates are not allowed for a particular key, VAX 
RMS rejects the operation with an RMS$_DUP error code. If duplicates are 
allowed, VAX RMS performs the operation. 

Subsequent sequential operations on a given index will always retrieve 
records with identical key values in the order in which the records were 
written. 

Table RMS-52 lists the control block fields read as input by the Update 
service. For additional information on the fields accessed by this service, 
see Part II. 


Table RMS-52 Update RAB Input Fields 


Field Name 

Option 

Description 

RABSW—ISI 


Internal stream identifier (required). 

RAB$L_RBF 


Record buffer address. 

RAB$I_RHB 


Record header buffer (applies only to variable 
with fixed control records). 

RAB$I_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Update services 
asynchronously. 


RAB$V_WBH 

Write locked: two buffers are allocated to 
allow multibuffering. 

RAB$W_RSZ 


Record size (required). 


Table RMS-53 lists the control block fields written as output by the Update 
service. 
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Table RMS-53 Update RAB Output Fields 


Field Name 
Description 

Option 

RAB$W_RFA 

Record's file address. 

RAB$I_STS 

Completion status code (also returned in Register 0). 

RAB$I_STV 

Status value. 


CONDITION 


VALUES 

RETURNED 

The following condition values are 

RMS$_ACT RMS$_ATR 

described in Appendix A: 

RMS$_ATW RMS$_BLN 


RMS$_BUG 

RMS$_BUG_DAP RMS$_CDA 

RMS$_CHG 


RMS$_CHK 

RMS$_CUR 

RMS$_DME 

RMSS—DNR 


RMS$_DUP 

RMS$_ENQ 

RMSS—EXP 

RMS$_FAC 


RMS$_FTM 

RMS$_IBF 

RMS$_IDX 

RMS$_IOP 


RMSS—IRC 

RMS$_ISI 

RMS$_NET 

RMS$_NETFAIL 


RMS$_NORMAL 

RMS$_OK _DUP 

RMS$_OK_IDX 

RMS$_PENDING 


RMS$_PLG 

RMS$_RAB 

RMSS—RBF 

RMS$_RER 


RMSS—RHB 

RMS$_RNL 

RMS$_RPL 

RMS$_RRV 


RMSS—RSA 

RMS$_RSZ 

RMS$_RVU 

RMS$_STR 


RMS$_SUC 

RMS$_SUP 

RMS$_SUPPORT 

RMS$_SYS 


RMS$_TRE 

RMSS—WPL 

RMS$_WBE 

RMSS—WER 

RMSS—WLK 
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$WAIT 

The Wait service suspends image execution until an asynchronous 
record service completes. Upon completion of the service, VAX 
RMS returns control to your program at the point following the Wait 
service call. 

FORMAT 

SYSSWAIT rab 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Wait service call. The rab argument is the address of the RAB control 
block. It can be either the RAB whose I/O request is in progress or some 
other RAB. 

DESCRIPTION 

The Wait service takes no arguments to define entry points for user-written 
completion routines; the completion routines are specified by the service 
being awaited. 

Any completion routines specified on the operation being awaited are 
declared as ASTs before VAX RMS returns control. They will be executed 
before the WAIT service completes unless ASTs are disabled. Completion 
routines are always executed as asynchronous system traps (ASTs). 

Table RMS-54 lists the control block fields read as input and written as 
output by the Wait service. For additional information on the fields accessed 
by this service, see Part II. 

Table RMS-54 Wait RAB Input and Output Fields 

Field 

Use Name Description 

Input RAB$W_ISI Internal stream identifier (required). 

RAB$I_STS Status completion code. 

Output RAB$L_STS Completion status code (also returned in Register 0). 
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CONDITION 

VALUES 

RETURNED 


The following condition values are described in Appendix A: 

RMS$_BLN RMSS—CDA RMS$_ISI RMS$_NORMAL 

RMS$_RAB RMS$_STR RMS$_SUC 

The VAX RMS completion status codes for the Wait service are determined by 
the VAX RMS service being awaited, unless the address of the RAB specified 
for the wait is different from that specified for the awaited operation. In this 
case, RMS$_NORMAL is returned. 
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$WRITE 

The Write service transfers a user-specified number of bytes 
(beginning on a block boundary) to a VAX RMS file of any file 
organization. 

FORMAT 

SYSSWRITE rab [,[err][,suc]] 

RETURNS 

VMS Usage: concLvalue 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 

ARGUMENTS 

rab 

VMS Usage: rab 

type: longword (unsigned) 

access: modify 

mechanism: by reference 

RAB control block whose contents are to be used as indirect arguments for 
the Write service call. The rab argument is the address of the RAB control 
block. 


err 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


sue 

VMS Usage: ast_procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

AST-level success completion routine that the Write service invokes if the 
operation is successful. The sue argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION You specify the number of bytes to be written by the Write service in the 

record size (RAB$W_RSZ) field of the RAB and the address of the buffer for 
the transfer in the record address field. In the bucket number (RAB$L_BKT) 
field, you indicate the virtual block number of the first block to be written; if 
this number is 0, the transfer starts with the block indicated by the NBP. 

A sequential file is automatically extended if you write a block past the end 
of the currently allocated space when using block I/O (or record I/O). For 
sequential files, VAX RMS maintains a logical end of file to correspond to the 
last block and highest byte written within the block. For relative and indexed 
files, you must use the Extend service when using block I/O. 

Table RMS-55 lists the control block fields read as input by the Write service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-55 Write RAB Input Fields 


Field Name 

Option 

Description 

RAB$L_BKT 


Bucket number: must contain the virtual block 
number of the first block to be written. 

RAB$W_ISI 


Internal stream identifier. 

RAB$I_RBF 


Record address. 

RAB$L_ROP 


Record-processing options. 


RAB$V_ASY 

Asynchronous: performs Write services 
asynchronously. 


RAB$V_TPT 

Truncate on Put: specifies that a Write service 
will truncate the file after the transferred data. 

RAB$W_RSZ 


Record size: indicates the transfer length, in 
bytes. 1 . 


Certain devices require that an even number of bytes be transferred. For further 
details, see the VAX/VMS I/O Reference Volume. 


Table RMS-56 lists the control block fields written as output by the Write 
service. 

Table RMS-56 Write RAB Output Fields 

Field Name Description 

RAB$W_RFA Record's file address: contains the virtual block number of the 
first block transferred. 

RAB$L_STS Completion status code (also returned in Register 0). 

RAB$L_STV Status value: contains the actual number of bytes transferred if 
an end-of-file error occurs. 
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CONDITION 

VALUES 

The following condition values are described 

in Appendix A: 

RETURNED 


RMS$_ACT 

RMS$_ATR 

RMSS—ATW 


RMS$_BLN 

RMS$_BUG_DAP 

RMS$_CDA 


RMS$_CONTROLC 

RMS$_CONTROLO 

RMS$_CONTROLY 


RMSS—DME 

RMS$_DNR 

RMS$_EOF 


RMSS—EXT 

RMS$_FAC 

RMS$_FTM 


RMS$_FUL 

RMS$_IOP 

RMS$_ISI 


RMS$_NET 

RMS$_NETFAIL 

RMS$_NORMAL 


RMSS—PENDING 

RMS$_RAB 

RMS$_RBF 


RMS$_RSA 

RMS$_RSZ 

RMS$_STR 


RMSS—SUC 

RMS$_SUP 

RMS$_SUPPORT 


RMS$_WBE 

RMS$_WER 

RMS$_WLK 
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A VAX RMS Completion Status Codes 


This appendix provides two listings of the VAX RMS completion status codes. 
See Part III for listing of the status codes applicable to individual VAX RMS 
services. 

% 

VAX RMS completion status error codes generally fall into one of four groups: 

• Programming errors 

• Program design errors 

• System environment errors 

• Opera tor/user errors 

Here is a brief description of each group: 

Error Group 
Programming Errors 

These errors are caused by incorrect programming and are usually detected 
during the early stages of developing and debugging a program that uses VAX 
RMS. Typical examples are missing values for required fields, referring to a 
RAB instead of a FAB, invalid address for a buffer, and so forth. This type of 
error is generally self-explanatory and usually requires only a minor change 
to the program. 

Program Design Errors 

These errors are caused by more subtle errors that may rarely occur, 
particularly if asynchronous record I/O, multistreamed sharing, or shared 
files are involved. These errors may occur long after a program has been 
in use and could require either a major program revision or the addition of 
substantial error recovery code to handle the error conditions. Record-lock 
errors, resource-exhaustion errors, and record-stream-currently-active errors 
are typical progam design errors. 

System Environment Errors 

These errors include hardware errors and VAX RMS or other system software 
errors that are not caused by your program. You may need to add substantial 
defensive error-handling code or you may be able to run the program again 
without error. 

Operator/User Errors 

These errors include operational errors by the user of the program, such as 
not mounting a device before running the program, or typing an invalid 
file specification. As with system environment errors, you may need to add 
substantial defensive error-handling code or simply reprompt the user for the 
correct information or user action. 
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These are conditions in which completion status codes may not be returned 
as expected: 

• The completion status codes that apply to the Close service do not include 
errors that can arise due to setting of the FAB$V_SCF and FAB$V_SPL 
options in the FAB$L_FOP field. If the request is submitted successfully, 
then a success completion code is returned, even if the request is found to 
be in error by the job controller process. 

• The Wait service has unique errors. This service can return any status 
code of the awaited operation. 

• Errors associated with output operations may not necessarily be reported 
as the status of that particular operation because modified I/O buffers are 
not always written out immediately. Such errors are reported as the status 
of a subsequent operation, which may be an input, output, or control 
operation. 

Procedures for signaling VAX RMS completion status codes are discussed 
in Section 2 for VAX languages other than VAX MACRO. VAX MACRO 
users should refer to Section 3 and the example programs in Section 4 for 
information on signaling VAX RMS errors. Note that certain errors may not 
be signaled using the FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_ 
STV fields; these are denoted below and in Section 2. 

A description of each completion status code is listed in this appendix. When 
an error description indicates that the STV field should be examined for a 
secondary status code, this usually indicates a non-VAX RMS completion 
status (such as an ACP completion status) or information that will be helpful 
in determining the error is contained in the STV field of the FAB or RAB. 
Such non-VAX RMS errors are not described in this document; see the 
VAX/VMS System Messages and Recovery Procedures Reference Manual. 

Please note that when you submit an SPR, you should also provide a copy of 
the file causing the error (usually magnetic tape is used). 

When using the debugger, use the debug command EXAMINE/CONDITION 
to view the message corresponding to the value in RO or the STS field or the 
STV field. For example, you can view the error codes in the STS and STV 
fields of the FAB at symbolic address (label) MYFAB when debugging a VAX 
MACRO program by entering the following commands: 

dbg> examine/condition myfab+fab$l_sts 

DBG> EXAMINE/CONDITION MYFAB+FAB$L_STV 

For additional information about the debugger, see the VAX/VMS Debugger 
Reference Manual. 

Table A-l lists the codes by hexadecimal values and includes a very brief 
description of each code. Table A-2 is ordered alphabetically and provides 
more detailed descriptions of the codes. 

Table A-1 Completion Status Hexadecimal Values and Codes 

Hex Value Status Code Message Text 

00010001 RMS$_SUC Normal successful completion (same as RMS$_NORMAL) 

00010001 RMS$_NORMAL Normal successful completion (same as RMS$_SUC) 

00010609 RMS$_CONTROLO Operation completed under CTRL/O 


A-2 






VAX RMS Completion Status Codes 


Table A- 

1 (Cont.) Completion Status Hexadecimal Values and Codes 

Hex Value 

Status Code 

Message Text 

00010611 

RMS$_CONTROLY 

Operation completed under CTRL/Y 

00010619 

RMS$_CREATED 

File did not exist—was created 

00010631 

RMS$_SUPERSEDE 

Created file superseded existing version 

00010651 

RMS$_CONTROLC 

Operation completed under CTRL/O 

00018009 

RMS$_PENDING 

Asynchronous operation not yet completed 

00018011 

RMS$_OK_DUP 

Record inserted had duplicate key 

00018019 

RMS$_0K_IDX 

Index update error occurred 

00018021 

RMS$_OK_RLK 

Record locked but read anyway 

00018029 

RMS$_OK_RRL 

Record locked against read but read anyway 

00018031 

RMS$_KFF 

Known file found 

00018039 

RMS$_OK_ALK 

Record is already locked 

00018041 

RMS$_OK_DEL 

Deleted record successfully accessed 

00018049 

RMS$_OK_RNF 

Nonexistent record successfully accessed 

00018051 

RMS$_OK_LIM 

Retrieved record exceeds specified key value 

00018059 

RMS$_OK_NOP 

XAB not filled in for block I/O 

00018061 

RMS$_OK_WAT 

Record locked after wait 

00018069 

RMS$_CRE_STM 

File was created in stream format 

00018198 

RMS$_BOF 

Beginning of file detected 

000181 AO 

RMSS—RNL 

Record not locked 

000181A8 

RMS$_RTB 

nnn byte record too large for user's buffer 

000181 BO 

RMS$_TMO 

Timeout period expired 

000181B8 

RMS$_TNS 

Terminator not seen 

000181CO 

RMS$_BES 

Bad escape sequence 

000181C8 

RMS$_PES 

Partial escape sequence 

0001825A 

RMS$_ACT 

File activity precludes operation 

00018262 

RMS$_DEL 

RFA-accessed record was deleted 

00018272 

RMS$_DNR 

Device not ready, not mounted, or unavailable 

0001827A 

RMSS—EOF 

End of file detected 

00018282 

RMS$_FEX 

File already exists, not superseded 

0001828A 

RMSS—FLK 

File currently locked by another user 

00018292 

RMSS—FNF 

File not found 

0001829A 

RMS$_PRV 

Insufficient privilege or file protection violation 

000182A2 

RMS$_REX 

Record already exists 

000182AA 

RMS$_RLK 

Target record currently locked by another stream 

000182B2 

RMS$_RNF 

Record not found 

000182BA 

RMS$_WLK 

Device currently write-locked 

000182C2 

RMS$_EXP 

File expiration date not yet reached 

000182CA 

RMS$_NMF 

No more files found 

000182D2 

RMS$_SUP 

Network operation not supported; DAP code = nnnn 
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Table A—1 (Cont.) Completion Status Hexadecimal Values and Codes 


Hex Value 

Status Code 

Message Text 

000182DA 

RMS$_RSA 

Record stream currently active 

000182E2 

RMS$_CRC 

Network DAP level CRC check failed 

000182EA 

RMSS—WCC 

Invalid wild card context (WCC) value 

000182F2 

RMS$_IDR 

Invalid directory rename operation 

0001830A 

RMS$_NOVALPRS 

SSEARCH operation not preceded by valid SPARSE 

000183F4 

RMS$_AID 

Invalid area ID = n 

000183FC 

RMS$_ALN 

Alignment options error for area ID = n 

00018404 

RMS$_ALQ 

Invalid allocation quantity (negative, or 0 on SEXTEND) 

0001840C 

RMS$_ANI 

Not ANSI D format 

00018414 

RMS$_AOP 

Allocation options error for area ID = n 

0001841C 

RMS$_BKS 

Bucket size too large (FAB) 

00018424 

RMSS—BKZ 

Inconsistent bucket size for area ID = n 

0001842C 

RMS$_BLN 

Invalid block length for control block (RAB/FAB) 

00018434 

RMS$_BUG 

Internal RMS error condition detected 

0001843C 

RMS$_BUG_DDI 

Invalid default directory 

00018444 

RMS$_BUG_DAP 

Data Access Protocol error detected; DAP code = nnnn 

0001848C 

RMS$_BUSY 

User structure (FAB/RAB) still in use 

00018494 

RMS$_CCR 

Cannot connect RAB 

0001849C 

RMS$_CHG 

Invalid key change in SUPDATE (CHG not set) 

000184A4 

RMS$_CHK 

Bucket format check failed for VBN = nnnn 

000184AC 

RMS$_C0D 

Invalid or unsupported type field in XAB at nnnn 

000184B4 

RMS$_CUR 

No current record (operation not preceded by $GET/$FIND) 

000184BC 

RMSS—DAN 

Invalid data area number for key = n 

000184C4 

RMS$_DEV 

Error in device name or inappropriate device type for operation 

000184CC 

RMSS—DIR 

Error in directory name 

000184D4 

RMS$_DME 

Dynamic memory exhausted 

000184DC 

RMS$_DNA 

Invalid default file name string address 

000184E4 

RMS$_DTP 

Invalid key data type for key = n 

000184EC 

RMS$_DUP 

Duplicate key detected (DUP not set) 

000184F4 

RMS$_DVI 

Invalid device ID value in NAM block 

000184FC 

RMS$_ESA 

Invalid expanded string address 

00018504 

RMS$_ESS 

Expanded string area too small 

0001850C 

RMS$_FAB 

Invalid FAB or FAB not accessible 

00018514 

RMSS—FAC 

Record operation not permitted by specified file access (FAC) 

0001851C 

RMS$_FLG 

Invalid key definition flags for key = n 

00018524 

RMSS—FNA 

Invalid file name string address 

0001852C 

RMS$_FNM 

Error in file name 

00018534 

RMS$_FSZ 

Invalid fixed control header size 

0001853C 

RMS$_F0P 

Invalid file options 
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Table A-1 (Cont.) Completion Status Hexadecimal Values and Codes 

Hex Value Status Code Message Text 


00018544 
00018554 
0001855C 
00018564 
0001856C 
00018574 
0001857C 
00018584 
0001858C 
00018594 
0001859C 
000185A4 
000185AC 
000185B4 
000185BC 
000185CC 
000185D4 
000185DC 
000185E4 
000185F4 
000185FC 
0001860C 
00018614 
0001861C 
00018624 
00018634 
0001863C 
00018644 
0001864C 
00018654 
0001865C 
00018664 
0001866C 
00018674 
0001867C 
00018684 
0001868C 
00018694 
0001869C 


RMS$_FUL 

RMS$_IAN 

RMS$_IDX 

RMS$_IFI 

RMSS—IMX 

RMS$_I0P 

RMS$_IRC 

RMS$_ISI 

RMS$_KBF 

RMS$_KEY 

RMS$_KRF 

RMSS—KSZ 

RMS$_LAN 

RMS$_RUNDOWN 

RMS$_LNE 

RMS$_MRN 

RMS$_MRS 

RMSS—NAM 

RMS$_NEF 

RMS$_N0D 

RMS$_NPK 

RMS$_0RG 

RMS$_PBF 

RMS$_PLG 

RMS$_P0S 

RMS$_QU0 

RMS$_RAB 

RMS$_RAC 

RMSS—RAT 

RMS$_RBF 

RMS$_RFA 

RMS$_RFM 

RMS$_RHB 

RMS$_RLF 

RMS$_R0P 

RMS$_RRV 

RMS$_RVU 

RMS$_RSS 

RMSS—RST 


Device full (insufficient space for allocation) 

Invalid index area number for key = n 

Index not initialized 

Invalid internal file identifier (IFI) value 

Invalid duplicate XAB or non-dense XAB at nnnn 

Operation invalid for file organization or device 

Illegal record encountered; VBN or record number = nnnn 

Invalid internal stream identifier (ISI) value 

Invalid key buffer 

Invalid record number key or key value 

Invalid key-of-reference for $GET/$FIND 

Invalid key size for $GET/$FIND 

Invalid lowest-level-index area number for key = n 

Operation invalid during RMS rundown 

Logical name translation count exceeded 

Invalid maximum record number or record number exceeds MRN 

Invalid maximum record size 

Invalid NAM block or NAM block not accessible 

Not positioned to EOF on SPLIT (sequential organization only) 

Error in node name 

No primary key defined for indexed file 
Invalid file organization value 
Invalid prompt buffer 

Error detected in file's prologue (reconstruct file) 

Invalid key position (greater than MRS) for key = n 

Error in quoted string 

Invalid RAB or RAB not accessible 

Invalid record access mode 

Invalid record attributes 

Invalid record buffer 

Invalid record's file address (RFA) 

Invalid record format 
Invalid record header buffer 
Invalid related NAM block 
Invalid record options 
Invalid RRV record encountered 

Error updating RRVs, some paths to data may be lost 
Invalid resultant string size 
Invalid resultant string address 
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Table A—1 (Cont.) Completion Status Hexadecimal Values and Codes 


Hex Value 

Status Code 

Message Text 

000186A4 

RMS$_RSZ 

Invalid record size 

000186AC 

RMS$_SEQ 

Primary key out of sequence (SEQ access) 

000186B4 

RMS$_SHR 

Invalid file sharing (SHR) options 

000186BC 

RMS$_SIZ 

Invalid key size for key = n 

000186C4 

RMS$_SQ0 

Operation not sequential (SQO set) 

000186D4 

RMSS—SYN 

File specification syntax error 

000186DC 

RMS$_TRE 

Error in index tree 

000186E4 

RMS$_TYP 

Error in file type 

000186EC 

RMS$_UBF 

Invalid user buffer 

000186F4 

RMS$_USZ 

Invalid user buffer size 

000186FC 

RMS$_VER 

Error in version number 

00018704 

RMS$_XNF 

Required XAB not found 

0001870C 

RMS$_XAB 

Invalid XAB or XAB not accessible at nnnn 

00018714 

RMS$_ESL 

Invalid expanded string length 

00018724 

RMS$_ENV 

Support for RMS service call or feature not present 

0001872C 

RMS$_PLV 

Unsupported prologue version 

00018734 

RMSS—MBC 

Invalid multiblock count 

0001873C 

RMS$_RSL 

Invalid resultant string length 

00018744 

RMS$_WLD 

Invalid wildcard operation 

0001874C 

RMS$_NET 

Network operation failed at remote node; DAP code = nnnn 

00018754 

RMS$_IBF 

Illegal bucket format in VBN = nnnn 

0001875C 

RMS$_REF 

Invalid key-of-reference = n 

00018764 

RMS$_IFL 

Index bucket fill size larger than bucket size for key = n 

0001876C 

RMS$_DFL 

Data bucket fill size larger than bucket size for key = n 

00018774 

RMS$_KNM 

Key name buffer not accessible for key = n 

0001877C 

RMS$_IBK 

LAN bucket size not equal to IAN bucket size for key = n 

00018784 

RMS$_KSI 

Index bucket will not hold two keys for key-of-reference = n 

0001878C 

RMS$_LEX 

Invalid SEXTEND for area n containing an unused extent 

00018794 

RMS$_SEG 

Overlapping segments or segmented key must be string for key = n 

000187AC 

RMS$_UPI 

UPI not set when sharing and BIO or BR0 set 

000187B4 

RMS$_ACS 

Error in access control string 

000187BC 

RMS$_STR 

User structure (FAB/RAB) became invalid during operation 

000187C4 

RMS$_FTM 

Network file transfer mode precludes operation (SQO set) 

000187CC 

RMSS—GBC 

Invalid global buffer count 

000187D4 

RMS$_DEADLOCK 

Deadlock detected 

000187DC 

RMS$_EXENQLM 

Exceeded enqueue quota 

00018804 

RMS$_IFF 

Invalid file attributes for requested file access 

0001C002 

RMSS—ACC 

ACP file access failed 

0001COOA 

RMS$_CRE 

ACP file create failed 
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Table A-1 (Cont.) Completion Status Hexadecimal Values and Codes 


Hex Value 

Status Code 

Message Text 

0001CO12 

RMS$_DAC 

ACP file deaccess failed during $CLOSE 

0001C01A 

RMS$_ENT 

ACP enter function failed 

0001C022 

RMS$_EXT 

ACP file extend failed 

0001C02A 

RMS$_FND 

ACP file or directory lookup failed 

0001C032 

RMS$_MKD 

ACP could not mark file for deletion 

0001C03A 

RMS$_DPE 

Device positioning error 

0001C042 

RMS$_SPL 

Spool or submit of command file failed on SCLOSE 

0001C04A 

RMS$_DNF 

Directory not found 

0001C0CC 

RMS$_ATR 

File attributes read error 

0001C0D4 

RMS$_ATW 

File attributes write error 

0001C0DC 

RMS$_CCF 

Cannot close file 

0001C0E4 

RMS$_CDA 

Cannot deliver AST 

0001C0EC 

RMS$_CHN 

Assign channel system service request failed 

0001C0F4 

RMS$_RER 

File read error 

0001C0FC 

RMS$_RMV 

ACP remove function failed 

0001C104 

RMS$_RPL 

Error detected while reading prologue 

0001C10C 

RMS$_SYS 

QIO system service request failed 

0001C114 

RMS$_WER 

File write error 

0001C11C 

RMS$_WPL 

Error detected while writing prologue 

0001C124 

RMS$_IFA 

Illegal file attributes detected (file header corrupted) 

0001C12C 

RMSS—WBE 

Error on write behind 

0001C134 

RMS$_ENQ 

ENQ system service request failed 

0001C13C 

RMS$_NETFAIL 

Network operation failed at remote node 

0001C144 

RMS$_SUPPORT 

Network operation not supported 

0001C14C 

RMS$_CRMP 

CRMPSC system service failed to map global buffers 

0001C15C 

RMS$_REENT 

File could not be renamed and recovery failed; file has been lost 

0001C16C 

RMS$_TMR 

SETIMR system service request failed 

Table A-2 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 



RMS$_ACC File access error; the STV field contains an ACP error code. Take corrective action 

appropriate to the STV status code. 


RMS$_ACS 

RMSS—ACT 

RMS$_AID 


Error in access control string of the node name. 

File activity precludes operation; operation attempted while other file I/O was in 
progress. Modify the source program to detect and respond to this condition. 

Bad area identification number field in allocation XAB; the STV field contains the 
area ID. 


RMS$_ALN 


Invalid alignment boundary type in allocation XAB; the STV field contains the area 
ID. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_ALQ 

Incorrect allocation quantity; the value exceeds the maximum allowed (Create service) 
or exceeds the maximum allowed or is equal to zero (Extend service). 

RMS$_ANI 

RMS$_AOP 

RMSS—ATR 

Records in a magnetic tape file are not ANSI D format. 

Invalid allocation option in allocation XAB; the STV field contains the area ID. 

Read error on file header; the STV field contains an ACP error code. Take corrective 
action appropriate to the STV status code, if possible. 

RMS$_ATW 

Write error on file header; the STV field contains an ACP error code. Take corrective 
action appropriate to the STV status code, if possible. 

RMS$_BES 

Bad escape sequence (terminals only, warning). Modify the source program to 
detect and recognize this condition or reenter the input specifying the correct escape 
sequence. 

RMS$_BKS 

Invalid bucket size in FAB or inconsistent record length. The bucket size specified in 
the FAB was larger than 63. If the bucket size was specified as zero, the maximum 
record size is too large. 

RMSS—BKZ 

RMS$_BLN 

Invalid bucket size in the allocation XAB; the STV field contains the area ID. 

Invalid value in block length field; this completion code is not available in the 

FAB$I_STS/FAB$I_STV or RAB$L_STS/RAB$L_STV fields. 

RMS$_BOF 

Beginning of file detected (warning); when the Rewind service or Space service 
was invoked, the file was positioned at its beginning. The STV field contains the 
number of blocks spaced. You may need to modify the source program to detect 
and respond to this condition. 

RMS$_BUG 

RMS$_BUG_DAP 

RMS$_BUG_DDI 

RMS$_BUSY 

Internal VAX RMS error detected. Submit an SPR. 

Data Access Protocol error. Submit an SPR. 

Invalid default directory. Submit an SPR. 

FAB or RAB cannot be used because either a prior operation needs to complete 
before VAX RMS can use the FAB or RAB for the requested operation, or the user 
illegally called VAX RMS from executive mode at AST level or from kernel mode 
and interrupted another VAX RMS operation. Use multiple I/O streams or use the 

Wait service as necessary. This completion code is not available in the FAB$I_STS 

/FAB$L_STV or RAB$L_STS/RAB$L_STV fields. 

RMS$_CCF 

For the $CLOSE service, an output file could not be closed successfully; user buffer 
identifies the file by its device ID and file ID. 

RMS$_CCR 

Cannot connect RAB; process has specified either a non-existent or inaccessible 
RAB. This usually results from one of the following actions: 

• The program tried to do block I/O (setting RAB$V_BIO in RAB$L_ROP) with 
multistreaming (setting FAB$V_MSE in FAB$B_SHR) 

• The program tried to connect to multiple RABs to a FAB without first setting the 
FAB$V_MSE in the FAB$B_SHR field 

• The program tried to use multistreaming with file access across DECnet 

RMS$_CDA 

Cannot deliver AST; the STV field contains the STS value of the operation. The 
AST limit quota for the process has probably been exhausted. You need to increase 
the quota or decrease the level of AST activity. Take corrective action for the actual 
operation based on the STV value. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMSS—CHG 

Attempted to change a key value when that attribute was not set by the key 
definition XAB key option flag. 

RMS$_CHK 

Index file bucket check byte mismatch; the bucket has been corrupted. The STV 
field contains the VBN of the bucket. This error can be caused by any of the 
following conditions: 

• The combination of a disk that had been backed up using standalone BACKUP 
and files that had the /NOBACKUP qualifier 

• Inadvertent modification of the file using block I/O or non-VAX RMS programs 

• Hardware, RMS, or other system software errors. 

RMS$_CHN 

Try to recreate the rest of the file. If the problem recurs and appears to be caused 
by VAX RMS or system software, submit an SPR. 

Channel assignment failure; the STV field contains a system error code. Take 
corrective action appropriate to the STV status code, if possible. 

RMSS—COD 

RMS$_CONTROLC 

RMS$_CONTROLO 

Invalid type code in XAB; the STV field contains the XAB address. 

Operation completed under CTRL/C; terminal I/O may have been truncated (success). 

Operation completed under CTRL/O; terminal output may have been truncated 
(success). 

RMS$_CONTROLY 

RMSS—CRC 

Operation completed under CTRL/Y; terminal I/O may have been truncated (success). 

Network DAP level CRC check failed on Close. The network link may be experiencing 
hardware errors. Retry the operation. 

RMS$_CRE 

ACP file creation failed. The STV field contains an ACP error code. Take corrective 
action appropriate to the STV status code. 

RMS$_CREATED 

File was created when the FAB$L_FOP FAB$V_CIF (create-if) option was specified; 
VAX RMS created the file because the file was not found. If the file was found, it 
was opened (not created) and RMS$_NORMAL is returned (success). 

RMS$_CRE_STM 

RMS$_CRMP 

File was created in stream format (success). 

For the Connect service, the requested number of global buffers is unobtainable; 
no global sections or an insufficient number of global pages or global page file 
entries were available to grant the requested number of global buffers. Reduce the 
number of global buffers requested in the FAB$W_GBC field and reattempt the 
Connect service, or wait until an orderly shutdown of the system can be arranged 
and increase the appropriate system generation parameters, then reattempt the 
operation. 

RMS$_CUR 

No current record; operation not immediately preceded by a successful Get or Find 
service. 

RMS$_DAC 

ACP file deaccess failed during Close. The file was deaccessed. The STV field 
contains an ACP error code. Take corrective action appropriate to the STV status 
code. 

RMS$_DAN 

Invalid data area number in key definition XAB; the STV field contains the key 
number. 

RMSS—DEADLOCK 

The VMS lock manager detected a deadlock. Modify the source program, if 
necessary. 

RMS$_DEL 

RFA-accessed record was deleted; the program attempted to access a previously 
deleted record. Modify the source program, if necessary. 
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Table A-2 (Cont.) Descriptions of VAX RMS Completion Status Codes 

Status Code Description 


RMS$_DEV 

RMS$_DFL 

RMS$_DIR 


RMS$_DME 

RMSS—DNA 

RMS$_DNF 

RMS$_DNR 

RMS$_DPE 


RMS$_DTP 

RMS$_DUP 

RMS$_DVI 

RMS$_ENQ 

RMS$_ENT 

RMS$_ENV 


Bad device or inappropriate device type for operation. 

Data bucket fill size larger than bucket size specified in the key definition XAB; the 
STV field contains the key number. 

Error in directory name; the directory name was specified incorrectly. For example, 
a directory or subdirectory name exceeded 39 characters in length, or the use of a 
logical name resulted in more than a directory name in the file specification. Verify 
the syntax of either the directory name in the file specification or the logical name, if 
a logical name was used. 

Dynamic memory exhausted. Occurs only if the related I/O segment in the control 
region is full and the file is either a direct access process permanent file or the user 
has disallowed the use of the program region for I/O buffers to RMS. 

Invalid default file specification string address. 

Directory not found; specified directory name does not exist on the specified device. 
Verify that the device and directory are specified correctly. Create the directory on 
that device or use a different directory. When performing an Open service, consider 
using a search list logical name if the same file exists in multiple device/directory 
locations. The STV field contains a system error code. Take corrective action 
appropriate to the STV status code. 

Device not ready, not mounted, or unavailable. Make sure that the volume is 
physically loaded, that the device is ready, and that the DCL command MOUNT has 
been completed successfully. Check that the correct controller is set on the drive. 
Reattempt the operation. 

Device positioning error; magnetic tape improperly positioned. Examine the RAB$L_ 
STV field for secondary status information; take corrective action appropriate to this 
information. Reattempt the operation. If this error persists, it may indicate a system 
software or hardware failure. Contact your system operator or manager. 

Invalid data type in key definition XAB; the STV field contains the key number. 

Duplicate key detected; key definition XAB key option flag not set to allow duplicate 
key values. 

Invalid device identification in the NAM block. 

Lock manager system service failed; the STV field contains a $ENQ system service 
error code. Take corrective action appropriate to the STV status code, if possible. 

ACP enter function failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

Environment error; support for the VAX RMS service or selected option is not 
present in system. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_EOF 

For Find or Get services, end of file detected; the program attempted to read beyond 
the last record in the file. If necessary, modify the source program to detect and 
respond to the condition. 

For a Read (block I/O) service, end of file detected. Checking for the logical end 
of file is performed only for the sequential file organization. If an RMS$_EOF error 
occurs, it implies that the first virtual block number specified was at or past the end 
of the file. If the RMS$_EOF error occurs during a transfer, the record size field is 
set to the number of bytes before the logical end of file. For the relative or indexed 
file organization, this status code indicates an attempt to read past the end of the 
currently allocated space. 

For a Write service (block I/O), end of file detected for a sequential file; implies that 
the file could not be extended. Determine whether sufficient disk space is available 
on the disk device in use (use the DCL command SHOW DEVICE). If insufficient 
space, purge or delete files that are no longer needed; then reattempt the operation. 

RMS$_ESA 

RMS$_ESL 

RMS$_ESS 

RMS$_EXENQLM 

Invalid expanded string area address in NAM block. 

Invalid expanded string length in NAM block. 

Expanded string area too short. 

Exceeded process enqueue limit. Reduce the number of locks held at one time and 
retry, or have the system manager increase this limit for your process, logout and 
login, and then retry the operation. 

RMS$_EXP 

File expiration date not yet reached; overwrite of magnetic tape files was attempted. 
If the file can be overwritten, remount the volume using the /OVERRIDE=EXPIRATION 
qualifier. (You must be the volume owner or have VOLPRO privilege to overwrite a 
volume.) Otherwise, use a different volume. 

RMS$_EXT 

ACP file extend failed. The STV field contains an ACP error code. Take corrective 
action appropriate to the STV status code, if possible. 

RMS$_FAB 

Invalid FAB; block identifier field incorrect. This completion code is not available in 
the FAB$L_STS/FAB$L_STV fields. 

RMSS—FAC 

Operation not allowed by the value set in the FAB$B_FAC field. 

For the Extend service, verify that the FAB$B_FAC field specifies put or update 
access for the file to be extended. Modify the source program if necessary. 

RMS$_FEX 

File already exists, not superseded; the program attempted to create or rename 
a file with the same file specification as an existing file. Choose a different file 
specification; delete the existing file (if a new file is to be created). For the Create 
service, consider using the FAB$L_FOP field FAB$V_SUP option to request that an 
existing file be superseded. 

RMSS—FLG 

Invalid combination of values in key XAB$B_FLG field; the STV field contains the 
key number. (Example: XAB$V_CHG or XAB$V_NUL for primary key.) 

RMS$_FLK 

File currently locked by another user; the program attempted to create or open a file 
that is currently being accessed by another user, and the file was not accessed for 
sharing. Wait until the other user deaccesses the file and reattempt the operation. 

RMS$_FNA 

RMS$_FND 

Invalid file specification string address in FAB. 

ACP file or directory lookup failed; error occurred during a directory search. The 

STV field contains an ACP error code. Take corrective action appropriate to the 

STV status code, if possible. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_FNF 

File not found. Check the file specification and verify that the device, directory, 
file name, and file type are correct. If a logical name was specified, verify that the 
current equivalence name assigned to the logical name is correct. Verify that the 
correct volume is mounted and that the file was not inadvertently deleted. 

RMSS—FNM 

RMSS—FOP 

RMS$_FSZ 

RMS$_FTM 

RMS$_FUL 

RMS$_GBC 

RMS$_IAL 

Syntax error in file name. 

Invalid file-processing options. 

Invalid fixed control area size in FAB (equal to 1 for print files). 

Network DAP file transfer mode does not permit operation. 

Device full; cannot create or extend file. 

Invalid global buffer count. 

Invalid argument list. Applies to the SYSSRMSRUNDWN, SYS$SETDFPROT, and 
SYSSSETDDIR services. See the VAX/VMS System Services Reference Manual. 

RMS$_IAN 

Invalid index area number in key definition XAB; the STV field contains the key 
number. 

RMS$_IBF 

RMS$_IBK 

Invalid bucket format; STV contains bucket VBN. Submit an SPR. 

Bucket size of lowest level of index area number (XAB$B_LAN) not equal to that of 
specified index area number (XAB$B_IAN field) in key definition XAB; the STV field 
contains the key number. 

RMS$_IDR 

Invalid directory rename operation; attempted to rename a directory file into 
a directory tree that contained the directory file. The directory would then be 
inaccessible. 

RMS$_IDX 

RMS$_IFA 

Index not initialized; internal VAX RMS error. Submit an SPR. 

Invalid file attributes; file header corrupted. Check the STV field for additional 
information. Take corrective action appropriate to the STV status code, if present. 

RMS$_IFF 

Invalid file attributes for requested access. Usually, this occurs when attempting to 
open an ANSI magnetic tape file for write access and the file has a nonzero value 
for its buffer offset value. VAX RMS does not allow the creation of a magnetic tape 
file with a nonzero buffer offset. You can, however, access such a file for read and 
write operations if you specify block I/O. 

RMS$_IFI 

Invalid internal file identifier in FAB; file already closed or not open (Close or Connect 
services), file already open or not closed (Create service), file not open (Display and 
Extend services), or file already open (other services). 

RMS$_IFL 

Index bucket fill size larger than bucket size specified in key definition XAB; the STV 
field contains the key number. 

RMS$_IMX 

More than one XAB of the same type or nondense XAB is present for the file; the 
STV field contains the XAB address. 

RMS$_IOP 

Invalid operation attempted; operation is one of following: (1 ) block I/O when 
record I/O access, (2) record I/O when block I/O access, (3) rewind of process 
permanent file, (4) inappropriate device type or file organization. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_IRC 

Invalid record encountered in file or invalid byte count field or control byte field 
contained in that record; the STV field contains the virtual block number for 
sequential and indexed files or the relative record number for relative files of the 
corrupted record. This error can be caused by the following conditions: 


• The combination of a disk that had been backed up using standalone BACKUP 


RMS$_ISI 

and files that had the /NOBACKUP qualifier 

• Inadvertent modification of files by block I/O or non-VAX RMS programs 

• Hardware errors, VAX RMS errors,or other system software errors. 

For sequential and indexed files, try to recreate the rest of the file. For relative files, 
reinsert the bad record with the Put service using the RAB$L_ROP field RAB$V_UIF 
option. If this does not solve the problem, submit an SPR. 

Invalid internal stream identifier in RAB; record stream already connected (Connect 
service) or was not connected (other services). 

RMS$_KBF 

RMS$_KEY 

Invalid key buffer address. 

Invalid record key for random operation to a relative file or invalid packed decimal 
key for an indexed file. 

RMS$_KFF 

RMSS—KNM 

Known file found; this code is reserved for DIGITAL usage only. 

Invalid key name buffer address in key definition XAB; the STV field contains the 
key number. 

RMS$_KRF 

RMS$_KSI 

Invalid key of reference in RAB$B__KRF field. 

The size of the index buckets specified for the key must be large enough to hold at 
least two key values: the STV value contains the key of reference. 

RMS$_KSZ 

RMS$_LAN 

Key size not equal to 4 (relative file) or key size too large (indexed file). 

Invalid index lowest-level-bucket area number in key definition XAB; the STV field 
contains the key number. 

RMS$_LEX 

RMS$_LNE 

Attempted to extend area containing an unused extent. 

Logical name error; resulted in recursion or invalid process permanent file equivalence 
string. 

RMS$_MBC 

RMS$_MKD 

Invalid multiblock count. Must not be greater than 127. 

ACP could not mark file for deletion. The STV field contains an ACP error code. 
Take corrective action appropriate to the STV status code, if possible. 

RMS$_MRN 

Invalid value for maximum record number (negative) or relative key greater than 
maximum record number. 

RMS$_MRS 

RMS$_NAM 

RMS$_NEF 

Invalid value for maximum record size. 

Invalid or inaccessible NAM block. 

Attempted to use the Put service to a sequential file when not positioned to end of 
file. 

RMS$_NET 

Network operation failed at remote node; the STV field contains a DAP code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_NETFAIL 

Network operation failed at remote node; the STV field contains an FAL status code. 
Take corrective action appropriate to the STV status code, if possible. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_NMF 

No more files found; the directory or volume set does not contain any more files that 
meet the file specification (wildcard operation). This is the normal status to indicate 
the end of a wildcard search operation. Modify the source program, if necessary, to 
detect and respond to this condition. 

RMS$_NOD 

RMSS—NORMAL 

RMS$_NOV ALPRS 

Node name error. 

Operation successful (synonym for RMS$_SUC) (success). 

Search service not preceded by a Parse service. Correct the source program to 
invoke the SPARSE service before invoking the SSEARCH service. 

RMS$_NPK 

RMS$_OK_ALK 

No primary key defined in key definition XAB when creating an indexed file. 

Record is already locked; the program attempted to lock a previously locked record. 
No action is usually required, although this can depend on application requirements 
(success). 

RMS$_OK_DEL 

Deleted record successfully accessed; a previously deleted record was read 
successfully. No action is usually required, although this can depend on application 
requirements (success). 

RMS$_OK_DUP 

Record inserted had duplicate key; the record was inserted successfully and had one 
or more key values that duplicated the values of other records (success). 

RMS$_OK_IDX 

Index update error occurred; the record was inserted successfully but an error 
occurred on index update, which could cause slow access to that record using 
that key path. Examine the value of the RMS error in the RAB$L_STV field. 

Take corrective action appropriate to the STV status code. File reorganization is 
recommended (success). 

RMS$_OK_LIM 

Retrieved record exceeds specified key value; the retrieved record exceeds the 
specified key value when the RAB$L_ROP RAB$V_LIM option was specified. It 
was read successfully. No action is usually required, although this can depend on 
application requirements (success). 

RMS$_OK _NOP 

XAB not filled in for block I/O; operation executed successfully when block I/O 
access was specified. One or more XABALL or XABKEY blocks were not filled. 

No action is usually required, although this can depend on application requirements 
(success). 

RMS$_OK_RLK 

Record locked but read anyway; the retrieved record was locked but was read 
successfully. No action is required (success). 

RMS$_OK_RNF 

Nonexistent record successfully accessed; a nonexistent record was read 
successfully. No action is required (success). 

RMS$_OK _RRL 

Record locked against read, but read anyway; a record locked against reading was 
read successfully. No action is required (success). 

RMS$_OK _W AT 

Record locked after wait; the retrieved record was locked but has been read 
successfully after a wait period. No action is required (success). 

RMS$_ORG 

RMS$_PBF 

RMS$_PENDING 

Unknown file organization. 

Invalid prompt buffer address. 

An asynchronous operation was initiated but is not yet completed; no action is 
required (success). 
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Table A-2 (Cont.) Descriptions of VAX RMS Completion Status Codes 

Status Code Description 


RMS$_PES 


RMS$_PLG 

RMS$_PLV 

RMS$_POS 

RMS$_PRV 


RMS$_QUO 

RMS$_RAB 

RMS$_RAC 

RMS$_RAT 

RMS$_RBF 

RMS$_REENT 


RMS$_REF 

RMS$_RER 

RMS$_REX 


RMS$_RFA 

RMS$_RFM 

RMS$_RHB 

RMS$_RLF 

RMSS—RLK 


RMS$_RMV 

RMSS—RNF 


Partial escape sequence (terminals only, warning); the user buffer was filled before 
a complete escape sequence was entered. The remainder of the escape sequence 
will be returned with the next input operation. Increase the size of the user buffer 
to allow escape sequences or modify the program, if necessary, to recognize and 
respond to this condition. 

Error in file prologue; file is corrupted. 

Prologue version unsupported. 

Invalid key position (greater than MRS) in key definition XAB; the STV field contains 
the key number. 

Insufficient privilege or file protection violation; the current process is denied access 
because of the file protection. Check the access rights associated with the file and 
change them if needed. If you are not the file owner or have insufficient privilege, 
request that the file owner change the protection. 

Error in quoted string. 

Not a valid RAB; block identifier field incorrect. This completion code is not available 
in the RAB$L_STS/RAB$L_STV fields. 

Invalid value in record access mode field of RAB. 

Record attributes invalid in FAB. 

Invalid record address. 

ACP enter function failed (for new file specification) after successfully removing the 
old file specification, which now could not be reentered. Examine the STV field for 
additional information. The file could not be renamed and recovery failed; the file has 
been lost. 

Invalid key of reference in XAB; key of reference was greater than number in file or 
equal to 255. 

File read error; the STV field contains a system error code. Take corrective action 
appropriate to the STV status code, if possible. 

Record already exists; while inserting a record into a relative file using random 
access mode, the specified record number is the same as an existing record; the 
new record was not written over the existing record. Note the condition. Modify 
the source program, if necessary, to detect and respond to this condition. You may 
want to specify the RAB$I_ROP field RAB$V_UIF option. 

Invalid record's file address contained in RAB. 

Invalid record format. 

Invalid or inaccessible record header buffer. 

Invalid or inaccessible related file block, or user has exceeded the limit of 255 related 
file names blocks, or related file name blocks are linked circularly. 

Target record currently locked by another stream; the requested record cannot be 
accessed. Modify the source program, if necessary, to detect and respond to this 
condition. 

ACP remove operation failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

Record not found; the requested record in an indexed or relative file either was never 
written or was deleted. Modify the source program, if necessary, to detect and 
respond to this condition. 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_RNL 

Record not locked (warning); no records were locked for this record stream when 
the operation was invoked. If necessary, modify the source program. 

RMSS—ROP 

RMS$_RPL 

Invalid record option. 

Error while reading prologue; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_RRV 

RMS$_RSA 

Invalid RRV record encountered in indexed file; file may be corrupted. 

Record stream currently active (asynchronous operations); operation attempted while 
an I/O request was outstanding for this record stream. 

RMS$_RSL 

RMS$_RSS 

RMS$_RST 

RMS$_RSZ 

RMS$_RUNDOWN 

RMS$_RTB 

Resultant string length field of NAM block invalid. 

Resultant string area size is too small. 

Invalid resultant string area address in NAM block. 

Invalid record size. 

Operation invalid during RMS rundown. 

Record too large for user's buffer (warning); the record just returned was too large 

for the user buffer provided. The RAB$I_STV field contains the size of the record; 

the returned record is truncated to the size of the user buffer. Modify the source 
program by increasing the size of the user buffer. You can determine the size of 
the largest record in a file using the DCL command ANALYZE/RMS—FILE or by 
examining the contents of the XABFHC field XAB$W_LRL after opening the file with 
the XABFFIC chained to the FAB. 

RMS$_RVU 

Error while updating RRVs; some paths to data may be lost. File reorganization is 
strongly recommended. 

RMS$_SEG 

Segmented key for key data type other than string. The STV field contains the key 
of reference. 

RMS$_SEQ 

Primary key of record to be written is not equal to or greater than key of previous 
record and RAB$B_RAC field set to RAB$V_SEQ. 

RMSS—SHR 

Invalid value in the file sharing field of FAB. This condition can be caused by 
attempting to access a sequential file that cannot be shared. (Only relative files, 
indexed files, and sequential files with 512-byte fixed-length records can be shared.) 

RMS$_SIZ 

Invalid key size specified in key definition XAB XAB$B_SIZO through XAB$B_SIZ7 
field; specified size exceeds maximum record size, not equal to defined length on 
binary and integer key data types, greater than 16 for packed decimal key data 
type, or equal to 0 for string or packed decimal. The STV field contains the key of 
reference. 

RMS$_SPL 

Spool or submit command file option to a Close service failed; the STV field contains 
a system error code. Take corrective action appropriate to the STV status code. 

RMS$_SQO 

Operation not sequential; file was opened with FAB$I_FOP field FAB$V_SQO 

option, random access is not permitted. 

RMS$_STR 

User structure (FAB/RAB) became invalid during the execution of a file or record 
operation. This completion code is not available in the FAB$L_STS/FAB$L_STV or 
RAB$L_STS/RAB$L_STV fields. 

RMS$_SUC 

RMS$_SUP 

Operation successful (synonym for RMS$_NORMAL) (success). 

Network operation not supported; the STV field contains a DAP code. Take 
corrective action appropriate to the STV status code, if possible. 

RMS$_SUPERSEDE 

Created file superseded existing version of same file; no action is required (success). 
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Table A-2 (Cont.) 

Descriptions of VAX RMS Completion Status Codes 

Status Code 

Description 

RMS$_SUPPORT 

Network operation not supported; the STV field contains a FAL/DAP status code. 
Take corrective action appropriate to the STV status code, if possible. 

RMSS—SYN 

RMS$_SYS 

Syntax error in file specification. 

Error in system QIO directive; the STV field contains the directive or QIO status 
code. Take corrective action appropriate to the STV status code, if possible. 

RMS$_TMO 

Timeout period expired (terminal input, locked record, or mailbox devices, warning); 
the Find, Get, or Read service did not complete. For terminal and mailbox devices, 
the characters (if any) received before the timeout period expired are discarded. 

For disk record operations, the requested record was locked for the entire timeout 
period and was not read. Modify the source program, if necessary, to detect this 
condition and reattempt the requested service. 

RMS$_TMR 

RMS$_TNS 

SETIMR system service request failed. 

Terminator not seen (terminals only; warning); the terminal Get service terminated 
when the user buffer was filled to capacity, before a terminator sequence was 
encountered. Subsequent Get services can retrieve additional characters from that 
input line, including the terminator character sequence, which is not in the current 
user buffer. Modify the source program to detect and respond to this situation 
or provide a user buffer large enough to contain an entire input line including the 
terminator character sequence. 

RMS$_TRE 

RMS$_TYP 

RMS$_UBF 

RMS$_UPI 

Index tree error; file is corrupted. 

Error in file type. 

Invalid user record area address. 

The FAB$B_SHR field FAB$V_UPI option not set when file sharing FAB$L_FOP field 
FAB$V_BIO or FAB$V_BRO option was set. 

RMS$_USZ 

RMS$_VER 

RMS$_WBE 

Invalid user record area size. 

Error in version number. 

Error writing behind; the STV field contains a system error code. Take corrective 
action appropriate to the STV status code, if possible. 

RMS$_WCC 

Invalid wildcard context value. Verify that the NAM block has not been inadvertently 
modified between VAX RMS service calls. 

RMS$_WER 

File write error; the STV field contains a system error code. Take corrective action 
appropriate to the STV status code, if possible. 

RMS$_WLD 

RMS$_WLK 

Invalid wildcard operation. 

Device currently write-locked when write access was attempted. Verify the status 
of the device; reset the write-lock switch, if necessary. Notify the system operator if 
the error cannot be corrected. 

RMS$_WPL 

Error while writing prologue; the STV field contains an ACP or system error code. 
Take corrective action appropriate to the STV status code, if possible. 

RMS$_XAB 

Not a valid XAB, not readable or writable, invalid code or length; the STV field 
contains the XAB address. 

RMS$_XNF 

Could not locate XAB needed for this operation. Modify the source program to 

include the XAB and specify the address of the XAB in the FAB$I_XAB or RAB$L_ 

XAB field. 
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APPENDIX B 


This appendix lists the format of each VAX RMS control block 
macro and includes special syntax notes that differ from the rules 
provided in Part I. Note that in this appendix the use of the term 
"macro" refers to a VAX MACRO macro. 
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VAX RMS Control Block Macros 

$FAB 


$FAB 


FORMAT 


The $FAB macro allocates storage for a FAB and initializes certain 
FAB fields with defaults and user-specified values. No value is 
returned for this assembly-time operation. 


$FAB ALQ=allocation-quantity, 
BKS=bucket-size, 

BLS=block-size, 

CHA N—MODE=channel-access-mode 
C TX=user-con text- value, 
DEQ=extension-quantity, 
DNA=default-filespec-address, 

DNM= <filespec> , 
DNS=default-filespec-string-size, 

FAr= <BIO BRO DEL GET PUT TRN 
UPD> , 

FNA=filespec-string-address, 

FNM= <filespec> , 
FNS=fHespec-string-size, 

<CBT CIF CTG DFW DL T 
MXV NAM NEF NFS OFF 
FOP= POS RCK RWC RWO SCF 
SPL SQO SUP TEF TMD 
TMP UFO WCK> , 
FSZ=header-size, 
GBC=global-buffer-count, 

LNM—MODE= logical-name-translation- 
access-mode, 

MRN=maximum-record-number, 

MRS=maximum-record-size, 

NA M=nam-address, 

[ IDX } 

ORG= l PEL L 
{ SEQ ) 

! cr 

<BLK FTN > 

PRN 
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VAX RMS Control Block Macros 

$FAB 


FIX 
STM 
STMCR 
RFM=\ STMLF 
UDF 
VAR 
VFC 

RTV=windo w-size, 

c W o = <DEL GET MSE NIL PUT 

bHM UPD UPI> , 

XA B=xab-address 


For a description of the control block fields that correspond to the $FAB 
macro arguments, see Section 5. In some cases, specific default values are 
assigned automatically when you omit an argument. These specific defaults 
are noted in the text that explains each field in Part I, Section 5. If there is no 
specific default, VAX RMS uses a default value of 0. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Part I, Section 3, 
under "Using the Control Block Initialization Macros." 

Note that multiple arguments can be specified for the FAC, FOP, RAT, and 
SHR arguments, but must be enclosed within (delimited by) less than ( <) 
and greater than (> ) signs. The DNM and FNM arguments must also be 
delimited by these signs. 

The DNM and FNM arguments contain ASCII characters and have no 
corresponding field in the FAB. If the DNM argument is present, VAX RMS 
places its appropriate address and size in the FAB$L_DNA and FAB$B_ 
DNS fields. Similarly, if the FNM argument is present, VAX RMS places its 
appropriate address and size in the FAB$L_FNA and FAB$B_FNS fields. 
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$FAB_STORE 


$FAB_STORE 

The $FAB_STORE macro moves user-specified values into fields 
of the specified FAB. The expanded $FAB_STORE code executes 
at run time on a previously initialized (allocated) FAB, in contrast to 
the $FAB macro, which initializes the FAB at assembly time. The 
$FAB_STORE macro must reside in a code program section. 


FORMAT $FAB_STORE fab=fab-address, 

ALQ=#allocation-quantity, 

BKS=#bucket-size, 

BLS=#block-size, 

CHAN—MODE=#channel-access-mode 

CTX=user-context-value, 

DEQ=#extension-quantity, 

DNA=default-filespec-address, 

DNS=#default-filespec-string-size, 

FAr= <BIO BRO DEL GET PUT TRN 
hAC UPD>, 

FNA=filespec-string-address, 

FNS=#filespec-string-size, 

<CBT CIF CTG DFW DL T 
MXV NAM NEF NFS OFF 
FOP= POS RCK RWC RWO SCF 
SPL SQO SUP TEF TMD 
TMP UFO WCK> , 
FSZ=#header-size, 
GBC=#global-buffer-count, 
LNM—MODE= 
#logical-name-translation- 
access-mode, 

MRN=#maximum-record-number, 

MRS=#maximum-record-size, 

NA M=nam-address , 
f >DX ) 

ORG=\rel \. 

1 SEQ J 
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$FAB_STORE 


ARGUMENTS 


{ CR 

<BLKFTN> 

PRN 
FIX 
STM 
STMCR 
RFM=\ STMLF 
UDF 
VAR 
VFC 

RTV=#windo w-size, 

qud= <DEL GET MSE NIL PUT 

* HH UPD UPI> , 

XA B=xab-address 


For a description of the control block fields that correspond to the $FAB_ 
STORE macro arguments, see Section 5. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The FAB argument fab-address is required for the $FAB_STORE macro and 
is not present for the $FAB macro. Conversely, the DNM argument filespec 
and FNM argument default-filespec are not available for the $FAB_STORE 
macro, although you can use the DNA/DNS and FNA/FNS arguments to 
specify file specifications at run time. 

Note that RO is usually used by the $FAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$NAM 

The $NAM macro allocates storage for a NAM block and initializes 
certain NAM fields with default values and user-specified values. No 
value is returned for this assembly-time operation. 

FORMAT 

$ NAM ESA=expanded-string-address, 
ESS=expanded-string-size, 

NOP- <noconcealpwd 

SRCHXABS SYNCHK> , 
RLF=related-file-nam-block-address, 
RSA=resultant-string-address, 
RSS=resultant-string-size 

ARGUMENTS 

For a description of the control block fields that correspond to the $NAM 
macro arguments, see Section 6. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Part I, Section 3, 
under "Using the Control Block Initialization Macros." 

Note that multiple arguments can be specified for the NOP argument, but 
they must be enclosed within less than ( < ) and greater than ( > ) signs. 
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$NAM_STORE 


$NAM—STORE 



The $NAM_STORE macro moves user-specified values into fields 
of the specified NAM block. The expanded $NAM_STORE code 
executes at run time on a previously initialized (allocated) NAM 
block, in contrast to the $NAM macro, which initializes a NAM block 
at assembly time. The $NAM_STORE macro must reside in a code 
program section. 

FORMAT 

$NAM —STORE NAM=nam-address, 

DID=#directory-iden tifica tion, 

D V\=#de vice-iden tifica tion, 
ESA=expanded-string-address, 
ESS=#expanded-string-size, 
FID=#file-identification, 

NOP- <NOCONCEAL PWD 

SRCHXABS SYNCHK> , 
RLF=related-file-nam-block-address, 

RSA=resultant-string-address, 

RSS=#resultant-string-size 

ARGUMENTS 

For a description of the control block fields that correspond to the $NAM_ 
STORE macro arguments, see Section 6. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The NAM argument nam-address is required for the $NAM_STORE macro 
and is not present for the $NAM macro. Also, the $NAM_STORE argument 
fields below are not available for the $NAM macro. 

• The DID argument directory-identification sets the NAM$W_DID field, 
which is a 3-word field used when the FAB$L__FOP field FAB$V_NAM 
option is set. This argument is usually specified by its symbolic address. If 
a register is used to contain a value for the NAM$W_DID field, do not use 
R12, because two contiguous registers must be used to contain the value of 
this 3-word field. Note that you cannot use the byte, word, or longword 
displacements for an offset, or for indexed or deferred addressing. 

• The DVI argument device-identification sets the NAM$T_DVI field, 
which is a 16-byte field used when the FAB$L_FOP field FAB$V_NAM 
option is set. This argument must be passed by its symbolic address. A 
register must not be specified to contain a value for this argument. 
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$NAM_STORE 


• The FID argument file-identification sets the NAM$W_FID field, which is 
a 3-word field used when the FAB$L_FOP field FAB$V_NAM option is 
set. This argument is specified by its symbolic address. If a register is used 
to contain a value for the NAM$W__FID field, do not use R12, because two 
contiguous registers must be used to contain the value of this 3-word field. 
Note that you cannot use the byte, word, or longword displacements for 
an offset, or for indexed or deferred addressing. 

Note that RO is usually used by the $NAM_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$RAB 

The $RAB macro allocates storage for a RAB and initializes certain 
RAB fields with defaults and user-specified values. You cannot use 
this macro within a sequence of executable instructions. No value is 
returned for this assembly-time operation. 

FORMAT 

$RAB BKT=bucket-code-number, 
CTX=user-context-value, 

FA B=fab-address, 

KBF=key-buffer-address, 

KRF=key-of-reference-number, 

KSZ=key-size, 

MBC=multiblock-count-number, 

MBF=multibuffer-count-number, 

PBF=promp t-buffer-address, 

PSZ=promp t-buffer-size, 
f KEY ) 

RAC=\ RFA \, 

{ SEQ ) 

RBF=record-buffer-address, 

RHB=record-header-buffer-address, 

<ASY BIO CCO CVT EOF EQNXT 

ETO FDL KGE KGT LIM LOA 

ROP= LOC NLK NXR NXT PMT PTA 

RAH REA RLK RNE RNF RRL 

TMO TPT UIF ULK WAT WBH> , 
RSZ=record-size, 

TMO=time-out-number-of-seconds, 

UBF=user-record-buffer-address, 

USZ=user-record-buffer-size, 

XA B=xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $RAB 
macro arguments, see Section 7. In some cases, specific default values are 
assigned automatically when you omit an argument. These specific defaults 
are noted in the text that explains each field in Section 7. If there is no 
specific default, VAX RMS uses a default value of 0. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Part I, Section 3, 
under "Using the Control Block Initialization Macros." 
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$RAB 


Note that multiple arguments can be specified for the ROP argument, but 
must be enclosed within less than ( <) and greater than (> ) signs. Note 
too that the arguments KGE and EQNXT are logically synonymous, as are the 
arguments KGT and NXT. 
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$RAB_ STORE 



The $RAB_STORE macro moves user-specified values into fields 
of the specified RAB. The expanded $RAB_STORE code executes 
at run time on a previously initialized (allocated) RAB, in contrast to 
the $RAB macro, which initializes the RAB at assembly time. The 
$RAB_STORE macro must reside in a code program section. 

FORMAT 

$RAB_STORE RAB=rab-address, 

BKT=#bucket-code-number, 

CTX=user-context-value, 

FA B=fab-address, 
KBF=key-buffer-address, 

KRF=#key-of-reference-number, 
KSZ=#key-s\ze, 

MBC=#multiblock-count-number, 

MBF=#multibuffer-count-number, 

PBF=prompt-buffer-address, 

PSZ=#prompt-buffer-size, 

( KEY ) 

RAC= | RFA \, 

{ SEQ J 

RBF=record-buffer-address, 
RFA=#record-file-address, 
RHB=record-header-buffer-address, 
<ASY BIO CCO CVT 

EOF EQNXT ETO FDL 
KGEKGTUMLOA 

ROp _ LOCNLKNXRNXT 

PMTPTA RAH REA 
RLKRNERNFRRL 

TMO TPTUIFULK 

WAT WBH> , 
RSZ=#record-size, 

TMO= ^ t i me ~ out ~ num ^ er ~°f~ 
seconds, 

UBF=user-record-buffer-address, 

USZ=#user-record-buffer-size, 

XA B=xab-address 
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ARGUMENTS 


For a description of the control block fields that correspond to the $RAB_ 
STORE macro arguments, see Section 7. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The RAB argument rab-address is required for the $RAB_STORE macro 
and is not present for the $RAB macro. Also, the RFA argument record-file- 
address is a value (not address), and it is not available for the $RAB macro. 
The value for the 3-word RAB$W__RFA field must be set before each RFA 
record access, which is used only if the RAC (RAB$B_RAC) field is set to 
RFA. 

This argument is specified by its symbolic address. If a register is used to 
contain a value for the RAB$W_RFA field, do not use R12, because two 
contiguous registers must be used to contain the value of this 3-word field. 
Note that you cannot use the byte, word, or longword displacements for an 
offset, or for indexed or deferred addressing. 

Note that multiple arguments can be specified for the ROP argument, but 
must be enclosed within less than ( <) and greater than (> ) signs. Note 
too, that the arguments KGE and EQNXT are logically synonymous as are the 
arguments KGT and NXT. 

Note that RO is usually used by the $RAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABALL 


The $XABALL macro allocates and initializes an XABALL, which 
allows extended control of file disk space allocation, both for 
initial allocation and later extension. No value is returned for this 
assembly-time operation. 


FORMAT 


$XABALL AID=area-identification-number, 
ANY 
CYL 

ALN=l LBN 
RFI 
VBN 

A L Q=alloca tion-quantity, 

AOP= <CBT CTG HRD ONC> 
BKZ=bucket-size, 


DEQ=extension-quantity, 
LOC=location-number , 


NXT=next-xab-address, 


RFh <f(1), f(2), f(3)> , 
VOL=volume-number 


ARGUMENTS For a description of the control block fields that correspond to the $XABALL 
macro arguments, see Section 8. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Part I, Section 3, 
under "Using the Control Block Initialization Macros." 

Note that multiple arguments can be specified for the AOP argument but 
must be enclosed within less than ( <) and greater than ( > ) signs. 
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$XABALL-STORE 

The $XABALL_STORE macro moves user-specified values into 
fields of the specified XABALL. The expanded $XABALL_STORE 
code executes at run time on a previously initialized (allocated) 
XABALL, in contrast to the $XABALL macro, which initializes an 

XABALL at assembly time. The $XABALI_STORE macro must 

reside in a code program section. 


FORMAT 


$XABALI_STORE XAB=xaba!\-address, 

AID=#area-identification-number, 


ANY 
CYL 

ALN=\ LBN 
RFI 
VBN 

ALQ=#allocation-quantity / 
aqP= <CBT CTG 
HRD ONC> , 
BKZ=#bucket-s\ze, 


DEQ=#extension-quantity, 

LOC=#location-number, 


NXT=next-xab-address, 


RFI=#related-file-identification, 

VOL=#volume-number 


ARGUMENTS For a description of the control block fields that correspond to the $ XABALL — 
STORE macro arguments, see Section 8. 

Arguments fall into several categories: value, address, keyword, and the 
address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros 
are described in Part I, Section 3, under "Using the Control Block Store 
Macros." 

The XAB argument xaball-address is required for the $XABALL—STORE 
macro and is not present for the $XABALL macro. Also, the RFI argument 
related file identification sets the XAB$W_RFI field, which is a 3-word field 
used when the XAB$B_ALN field XAB$V_RFI option is set. This argument 
is usually specified by its symbolic address. If a register is used to contain 
a value for the XAB$W_RFI field, do not use R12, because two contiguous 
registers must be used to contain the value of this 3-word field. Note that 
you cannot use the byte, word, or longword displacements for an offset, or 
for indexed or deferred addressing. 
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Note that RO is usually used by the $XABALL—STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABDAT 



The $XABDAT macro allocates and initializes an XABDAT. No value 
is returned for this assembly-time operation. 

FORMAT 

$XABDAT EDT=date-time / 

NX T=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABDAT 
macro arguments, see Section 9. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 
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$XABDAT_STORE 

The $XABDAT_STORE macro moves user-specified values into 
fields of the specified XABDAT. The expanded $XABDAT_STORE 
code executes at run time on a previously initialized (allocated) 
XABDAT, in contrast to the $XABDAT macro, which initializes an 
XABDAT at assembly time. The $XABDAT_STORE macro must 
reside in a code program section. 


FORMAT $XABDAT_STORE XAB=xabdat-address, 

CDT=#creation-date-time, 
ED T=#expiration-date-time, 
RDT=#revision-date-time, 

R VN=#re vision-number, 
NXT=next-xab-address 


ARGUMENTS For a description of the control block fields that correspond to the $XABDAT_ 
STORE macro arguments, see Section 9. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabdat-address is required for the $XABDAT_STORE 
macro and is not present for the $XABDAT macro. Also, the arguments 
below differ from the general rules. 

• The CDT argument creation-date-time sets the XAB$Q_CDT field, which 
is a quadword field. However, if a register is used to contain a literal 
value for the XAB$Q_CDT field, do not use R12, because two contiguous 
registers must be used to contain the value of this quadword field. 

• The EDT argument expiration-date-time sets the XAB$Q_EDT field, 
which is a quadword field. The rules for the other time fields (see above) 
also apply to this one. 

• The RDT argument revision-date-time sets the XAB$Q_JRDT field, which 
is a quadword field. The rules for the other time fields (see above) also 
apply to this one. 

Note that RO is usually used by the $XABDAT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABFHC 



The $XABFHC macro allocates and initializes an XABFHC. No value 
is returned for this assembly-time operation. 

FORMAT 

$XABFHC NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABFHC 
macro arguments, see Section 10. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 
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$XABFHC_STORE 



The $XABFHC_STORE macro moves user-specified values into 
fields of the specified XABFHC. The expanded $XABFFIC_STORE 
code executes at run time on a previously initialized (allocated) 
XABFHC, in contrast to the $XABFHC macro, which initializes an 
XABFHC at assembly time. The $XABFHC_STORE macro must 
reside in a code program section. 

FORMAT 

$XABFHC_STORE XAB=xabfhc-address, 

NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABFHC_ 
STORE macro arguments, see Section 10. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabfhc-address is required for the $XABFHC_STORE 
macro and is not present for the $XABFHC macro. 

Note that R0 may be used by the $XABFHC_STORE macro; thus, R0 is not 
preserved and does not contain a return status. 
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$XABKEY 


The $XABKEY macro allocates and initializes an XABKEY. No value 
is returned for this assembly-time operation. 


FORMAT 


$XABKEY DAN=data-bucket-area-number, 
DFL=data-bucket-fill-size, 

BN2 
DBN2 
BN4 
DBN4 
BN8 
IN2 
DIN2 

DTP=\ m 
DIN4 
IN8 
DIN8 
PAC 
DPAC 
STG 
DSTG 

<CHG DAT—NCMPR DUP 
FLG= IDX—NCMPR 

KEY—NCMPR NUL> , 

I A N=index-bucket-area-number, 
IFL=index-bucket-file-size, 


KNM=key-name-buffer-address, 

LA N=lo west-level-index-area-number, 

NUL=null-key-value, 

NXT=next-xab-address, 

POS= <position,...> , 

PROLOG=prologue-level, 

REF=key-of-reference-value, 

SIZ= <size,...> 
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ARGUMENTS For a description of the control block fields that correspond to the $XABKEY 

macro arguments, see Section 11. 

Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Part I, Section 3, 
under "Using the Control Block Initialization Macros." 

Multiple arguments can be specified for the FLG argument, but must be 
enclosed within (delimited by) less than ( <) and greater than (> ) signs. 
Defaults are applied to the XAB$B_FLG field only if no FLG argument is 
specified. Consider the following: 

KEY.l: $XABKEY REF=1, P0S=O, SIZ=10 

This line specifies the key for alternate index 1. Therefore the macro will 
default the XAB$B_FLG field to allow duplicates and changes (the default 
for alternate keys). However, if an FLG argument is explicitly specified, the 
results are different, as shown below. 

KEY_2: $XABKEY REF=1, P0S=0, SIZ=10, FLG=CHG 

In this case, only the CHG option will be set in the XAB$B_FLG field, leaving 
the DUP option cleared, which means that duplicates will not be allowed on 
this key. 

Depending on whether the key being defined is simple or segmented, you 
would use one of the following two formats for the POS and SIZ arguments: 

POS=position 


SIZ=size 

or 

POS=<positionO,...,position7> 


SIZ=<8izeO.size7> 

You must include the angle brackets for multiple argument key positions and 
sizes. 
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$XABKEY_STORE 

The $XABKEY_STORE macro moves user-specified values into 
fields of the specified XABKEY. The expanded $XABKEY_STORE 
code executes at run time on a previously initialized (allocated) 
XABKEY, in contrast to the $XABKEY macro, which initializes the 
XABKEY at assembly time. The $XABKEY_STORE macro must 
reside in a code program section. 


FORMAT $XABKEY_STORE XAB=xabkey-address, 

DAN=#data-bucket-area-number, 


DFL=#data-bucket-fill-size. 


DTP- 


FLG= 


BN2 

DBN2 

BN4 

DBN4 

BN8 

IN2 

DIN2 

IN4 

DIN4 

IN8 

DIN8 

FAC 

DPAC 

STG 

DSTG J 

<CHG DAT-NCMPR 
DUPIDX—NCMPR 
KEY—NCMPR NUL> , 


IAI\j= #index-bucket- 
area-number, 
IFL=#index-bucket-fill-size, 
KNM= key-name-buffer- 
address, 

#lowest-level-index- 

area-number, 

NUL=#null-key-value, 

NXT=next-xab-address, 


POS= <position,...> , 
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PROLOG=#prologue-le vel, 
REF=#ke y-of-reference-value, 
SIZ= <size,...> 


ARGUMENTS For a description of the control block fields that correspond to the $XABKEY_ 

STORE macro arguments, see Section 11. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabkey-address is required for the $XABKEY_STORE 
macro and is not present for the $XABKEY macro. The POS and SIZ 
arguments can be either a symbolic address or a list of up to eight values, 
where each literal value must be preceded by a number sign (#), and 
the entire list must be enclosed within less than and greater than signs 
( <#value, ...,#value> ). The number of POS and SIZ values must be equal. 
Alternatively, each POS and SIZ value can be specified as an argument, using 
the form 

POSO = #value, P0S1 = #value.P0S7 = #value 

SIZO = #value, SIZ1 = #value, .... SIZ7 = #value 

Note that RO is usually used by the $XABKEY_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABPRO 



The $XABPRO macro allocates and initializes a XABPRO. No value 
is returned for this assembly-time operation. 

FORMAT 

SXABPRO ACLBUF=ACL-buffer-address, 

ACLCTX= <ACL-context> , 
ACLSIZ=ACL-buffer-size, 

MTACC= magnetic-tape- 
accessibility, 
NXT=next-xab-address, 
ppO= <system, owner, 
group, world> , 

PROT—OPT= <PROPOGATE> , 

UIC= <group, member> 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABPRO 
macro arguments, refer to Section 12. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 

For the MTACC argument, an ASCII radix indicator is required. For example, 
the letter Z is entered as the accessibility character with the following macro 
expression: 

$XABPRO MTACC=~A/Z/ 

In this example, the circumflex character (*) followed by an uppercase A 
character (~A ) indicates that ASCII text will follow. The two slash characters 
(//) delimit the ASCII text. VAX RMS will convert all lowercase characters 
to uppercase. No other modification will be made. 

For the PRO argument, the angle brackets are required syntax, and each 
user class must be separated from the others by a comma. When you omit a 
class to use the default protection, you must retain the comma to indicate the 
omission, unless no other class follows. 

To allow all system users read and write access, use the default file protection 
for the file owner (by omission), allow group users read access, and use the 
default for world users, you would specify <RW„R> . You may specify all, 
some, or none of the access characters and place multiple characters in any 
order, for each user class. 

Here is a listing of the user classes together with the letters used to represent 
them: 

• R—read access 

• W—write access 

• E—execute access 
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• D—delete access 

The absence of a code specifies that the access associated with the code is 
denied to the user. 

A user is granted the maximum number of types of access rights for each of 
the classes to which he belongs. 

For the UIC argument, the value for the group item must be in the range 
of 0 to 37777; the value for the member item must from 0 to 177777. Note 
that the maximum values (37777 and 177777) are reserved for DIGITAL use 
only. The group number and member number must be enclosed within angle 
brackets, placed in the order <group,member> , and be separated by a 
comma. Each number is interpreted as an octal number. 
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$XABPRO_STORE 



The $XABPRO_STORE macro moves user-specified values into 
fields of the specified XABPRO. The expanded $XABPRO_STORE 
code executes at run time on a previously initialized (allocated) 
XABPRO, in contrast to the $XABPRO macro, which initializes an 
XABPRO at assembly time. The $XABPRO_STORE macro must 
reside in a code program section. 

FORMAT 

$XA B P R O—STORE XA B=xabpro-address, 

ACLBUF=ACL-buffer-address, 
ACLCTX=# <ACL-context> , 

A CLS\Z=#A CL-buffer-size, 

MTACC= # ma 9 net,c ~ ta P e - 
accessibility, 

NXT=next-xab-address, 

Prq= <system, owner, 
group, world> , 
PROT—OPT= <PROPOGATE> , 
UIC=#uic-value 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABPRO_ 
STORE macro arguments, see Section 12. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabpro-address is required for the $XABPRO_STORE 
macro and is not present for the $XABPRO macro. Also, the following 
arguments do not comply with the general rules: 

• The PRO argument (file protection) can be either a symbolic address or 
a list of keyword values. If you specify a list of keywords, it must be 
delimited by less than ( <) and greater than (> ) signs without the 
number sign (#), such as PRO= <RWED,RWED,R,R> . 

• The UIC argument (group,member) can be either a symbolic address 
or a list of two data values. If the data values are constants, they must 
be specified with an octal radix without a preceding number sign (#). 

This argument can be passed by its symbolic address or by using a VAX 
MACRO expression. 

Note that RO is usually used by the $XABPRO_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABRDT 



The $XABRDT macro allocates and initializes a XABRDT. No value 
is returned for this assembly-time operation. 

FORMAT 

$XABRDT NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABRDT 
macro argument, see Section 13. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 
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$XABRDT—STORE 



The $XABRDT_STORE macro moves user-specified values into 
fields of the specified XABRDT. The expanded $XABRDT_STORE 
code executes at run time on a previously initialized (allocated) 
XABRDT, in contrast to the $XABRDT macro, which initializes the 
XABRDT at assembly time. The $XABRDT_STORE macro must 
reside in a code program section. 

FORMAT 

$XABRDT_STORE XAB=xabrdt-address, 

RD T=#re vision-date-time, 

RVN=#revision-number, 

NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABRDT_ 
STORE macro arguments, see Section 13. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabrdt-address is required for the $XABRDT_STORE 
macro and is not present for the $XABRDT macro. Also, the RDT argument 
revision-date-time and RVN argument revision-number are not present 
in the $XABRDT macro. The RDT argument revision-date-time is usually 
passed by its symbolic address. However, if a register is used to contain a 
value for the XAB$Q_RDT field, do not use R12, because two contiguous 
registers must be used to contain the value of this quadword field. 

Note that RO is usually used by the $XABRDT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABSUM 



The $XABSUM macro allocates and initializes a XABSUM. No value 
is returned for this assembly-time operation. 

FORMAT 

$XABSUM NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the SXABSUM 
macro argument, see Section 14. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 
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$XABSUM-STORE 



The $XABSUM_STORE macro moves user-specified values into 
fields of the specified XABSUM. The expanded $XABSUM_STORE 
code executes at run time on a previously initialized (allocated) 
XABSUM, in contrast to the $XABSUM macro, which initializes the 
XABSUM at assembly time. The $XABSUM_STORE macro must 
reside in a code program section. 

FORMAT 

$XA BS U M _STORE XA B=xabsum-address, 

NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the 
$ XABSUM—STORE macro arguments, see Section 14. 

Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabsum-address is required for the $XABSUM—STORE 
macro and is not present for the $XABSUM macro. 

Note that RO may be used by the $XABSUM —STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABTRM 



The $XABTRM macro allocates and initializes a XABTRM. No value 
is returned for this assembly-time operation. 

FORMAT 

$XABTRM ITMLST=item-list-address, 

ITMLST—LEN=item-list-length, 

NXT=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the $XABTRM 
macro arguments, see Section 15. 

Rules applicable to arguments are described in Part I, Section 3, under "Using 
the Control Block Initialization Macros." 
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$XABTRM 

-STORE 


The $XABTRM_STORE macro moves user-specified values into 
fields of the specified XABTRM. The expanded $XABTRM—STORE 
code executes at run time on a previously initialized (allocated) 
XABTRM, in contrast to the $XABTRM macro, which initializes an 
XABTRM at assembly time. The $XABTRM_STORE macro must 
reside in a code program section. 

FORMAT 

$XABTRM XAB=xabtrm-address, 

ITMLST=item-list-address, 

ITMLST_LEN=#item-list-length, 

NX T=next-xab-address 

ARGUMENTS 

For a description of the control block fields that correspond to the 
$XABTRM—STORE macro arguments, see Section 15. 


Arguments fall into several categories: values, addresses, keywords, and 
the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Part I, Section 3, under "Using the Control Block Store Macros." 

The XAB argument xabtrm-address is required for the $XABTRM—STORE 
macro and is not present for the $XABTRM macro. 

Note that RO is usually used by the $XABTRM—STORE macro; thus, RO is 
not preserved and does not contain a return status. 
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modes supported by VAX RMS* 1-1 
run-time options under VAX RMS* 1-2 
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See ACL 
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See XAB$L_ACLBUF field 
Access control list buffer size field 
See XAB$W_ACLSIZ field 
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See XAB$I_ACLCTX field 

Access control list error status field 

See XAB$I_ACLSTS field 

Access control list length field 
See XAB$W_ACLLEN field 
Access specification 

list of mask values* 12-5 
ACE (access control list) 

VAX RMS limitation* 12-2 
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conversion methods* 12-2 
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avoiding use of *2-4 
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See XAB$B_ALN field 
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See XABALL block 
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See FAB$L_ALQ field 
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See XAB$L_ALQ field 
Area default extension quantity field 
See XAB$W_DEQ field 
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program example *4-9 
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specifying as run-time values *3-9 
to FAB* 1-2 
to RAB* 1-4 
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new FAB address field *2-5 
passing to VAX RMS service *3-10 
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delimiting in control block fields *3-6, 3-7 
Asynchronous I/O option 
See RAB$V_ASY option 
Asynchronous operation 

contrasted with synchronous operation • 2-7 
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Backup date and time field 
See XAB$Q_BDT field 
BID field *2-1 
SBINTIM *3-10 
BLN field *2-1 
Block boundary option 
See FAB$V_BLK option 
Block code field 
See COD field 
Block I/O 

additional services that use *4-25 
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how implemented by VAX RMS services *4-25 

how to execute *4-26 
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processing services *3-5 

program example *4-27 

requirements for mixing with record 1/0*4-25 
restrictions to *4-24 
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Block I/O (cont'd.) 
specifying* 4-25 

use of next block pointer for sequential files 
4-27 

with multiple record streams *4-26 
with record I/O processing • 4-27 
Block I/O execution 

contrasted with record I/O execution • 4-26 
Block I/O option 

See FAB$V_BIO option 
See RAB$V_BIO option 
Block identifier field 
See BID field 
See FAB$B_BID field 
See NAM$B_BID field 
See RAB$B_BID field 
Block length field 
See BLN field 
See FAB$B_BLN field 
See NAM$B_BLN field 
See RAB$B_BLN field 
in NAM block*6-4 
in XABPRO* 12-4 
Block length field in XABALL 
See XAB$B_BLN field 
in XABALL*8-5 
Block length field in XABDAT 
See XAB$B_BLN field 
Block length field in XABFHC 
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file organization considerations*5-4 
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See RAB$L_BKT field 
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See FAB$B_BKS field 


Bucket size field in XABALL 
See XAB$B_BKZ field 
Bucket size field in XABFHC 
See XAB$B_BKZ field 
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minimizing* 11-3 
BYTLM quota 

limiting size of user's ACL buffer* 12-3 
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Caller access mode *5-5 
Calling sequence *2-4 
Cancel CTRL/O option 
See RAB$V_CCO option 
Carriage return option 

See also FAB$V_CR option 
See CR option 
CDT argument • B-17 
Channel access mode subfield 

See FAB$V_CHAN_MODE subfield 
CHG (change) option 

to XAB$B_FLG field • B-21 
SCLOSE • 3-9 
Close service*RMS-1 
condition values*RMS-3 

See also Completion status codes 
contrasted with Disconnect service *4-5 
control block input fields*RMS-2 
control block output fields*RMS-2 
function *4-1 
introduced *4-1 
limitations with XABs* RMS-2 
use restriction • RMS-2 
use restrictions*RMS-1 
COD field *2-1 
Comment separator 

use in VAX RMS coding *3-6 
Completion routine 

condition for AST execution • 3-11 
service macro arguments *3-11 
Completion status code 
description *2-5 
descriptions* A-7 to A-17 
errors for inaccessible control block condition* 
2-6 

handling *3-12 

hexadecimal values *A-2 to A-7 
listing by group* A-1 

listing conditions when not returned* A-2 
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Completion status code (cont'd.) 
operator/user error group* A-1 
programming design error group* A-1 
programming error group* A-1 
severity codes *2-5 
system environment error group* A-1 
testing • 2-5 

use with debugger* A-2 
Completion status code field 
See FAB$L_STS field 
See RAB$L_STS field 
Completion status field 

as alternative to use of R0*2-4 
Completion status value field 
See FAB$L_STV field 
See RAB$L_STV field 
Completion value *2-4 
Condition value *2-5 

See also Completion status codes 
signaling convention • 2-6 
Connect service*RMS-4 

comparing positioning for various file 
organizations • RMS-5 
condition values*RMS-7 
connecting record stream • 4-5 
control block input fields*RMS-6 
control block output fields*RMS-6 
program example *4-13 
use with multiple keys *4-13 
Contiguous best try option 
See FAB$V_CBT option 
Contiguous option 

See FAB$V_CTG option 
Continuation character (-) 

use in VAX RMS coding *3-6 
Control block 

dual purpose* 1-4 

field name conventions*2-2 

for extended VAX RMS attributes* 1-3 

for VAX RMS file name operations* 1-3 

for VAX RMS file services* 1-2 

for VAX RMS record services* 1-4 

macro names *3-2 

requirements for valid default values* 1-4 

symbolic bit offset *2-3 

symbolic constant (keyword) value *2-4 

symbolic naming exceptions*2-3 

symbolic offsets *2-2 

types of macros *3-1 

use restrictions*2-1 

use with VAX languages • 2-1 


Control block store macro 
description *3-1 
example *3-9 
placement guidelines*3-8 
requirement for number sign *3-8 
use of RO* 3-8 
Control routine *4-30 
Control routines 

SYSSRMSRUNDWN • RMS-92 
SYSSSETDDIR* RMS-93 
SYSSSETDFPROT • RMS-94 
CONVERT command *4-9 
Convert option 

See RAB$V_CVT option 
SCREATE • 3-9, 3-10 
CREATE/FDL command *4-9 
Create-if option • 4-1 

See also FAB$V_CIF option 
Create service • RMS-8 

condition values • RMS-16 
contrasted with Open service *4-1 
control block input fields*RMS-9 
control block output fields • RMS-12 
function *4-1 

handling search list*RMS-9 
invoking • 4-1 
program example *4-2 
prologue level*RMS-16 
using the create-if option • RMS-15 
using the NAM block*RMS-13 
using to create indexed files*RMS-15 
XAB overridein various fields*RMS-9 
Creation date and time field 
See XAB$Q_CDT field 
CR option *4-4 
CTG option *4-4 
CTRL/Z 

Get service completion status code logic* 
RMS-46 

using as end-of-file marker*RMS-46 
using to terminate Get service* RMS-46 
Current position option 
See FAB$V_POS option 


D 


DAP(data access protocol)* 1-1 
Data access protocol 
See DAP 
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Data bucket area number (DAN) 
program example *4-9 
Data bucket area number field 
See XAB$B_DAN field 
Data bucket fill size (DFL) 
program example*4-9 
Data bucket fill size field 
See XAB$W_DFL field 
Data bucket size field 
See XAB$B_DBS field 
Data level 

comparing for primary and alternate keys* 11-3 
Data type of key field 
See XAB$B_DTP field 
Date/time extended address block 
See XABDAT block 
Date and time XAB 
See XABDAT 
Debugger 

use with completion status codes* A-2 
DECnet remote file access 

specifying maximum record size *5-21 
Default extension quantity field 
See FAB$W_DEQ field 
Default file extension quantity field in XABFHC 
See XAB$W_DXQ field 
Default file specification string address field 
See FAB$L_DNA field 
Default file specification string size field 
See FAB$B_DNS field 
Default global buffer count field 
See XAB$W_GBC field 
Deferred write option 

See FAB$V_DFW option 
Delete on close option 
See FAB$V_DLT option 
Delete service • RMS-18 
condition values*RMS-19 

See also Completion status codes 
control block input fields*RMS-19 
control block output fields • RMS-19 
program example *4-20 
requirements • RMS-19 
use restrictions*RMS-18 
Delete service option 
See FAB$V_DEL option 
Delete sharing option 

See FAB$V_SHRDEL option 
Delimiter 

using in control block arguments*3-5, 3-6, 3-7 


SDEVDEF macro 

source of DEV field bit definitions*5-7 
Device characteristics field 
See FAB$L_DEV field 
Device identification field 
See NAM$T_DVI field 
Device name address descriptor 
See NAM$L_DEV 
Device name address field 
See NAM$L_DEV field 
Device name length field 
See NAM$B_DEV field 
Device name size descriptor 
See NAM$B_DEV 
Digital Multinational Character Set 
VAX RMS use of *2-7 
Directory address descriptor 
See NAM$L_DIR 
Directory identification field 
See NAM$W_DID field 
Directory name length address field 
See NAM$L_DIR field 
Directory name length field 
See NAM$B_DIR field 
Directory size descriptor 
See NAM$B_DIR 
Disconnect service*RMS-20 
condition values*RMS-21 

See also Completion status codes 
control block input fields*RMS-21 
control block output fields*RMS-21 
program example *4-13 
using with multiple RABs* RMS-21 
Disk cluster boundary 

determining allocation quantity *5-3 
Display service*RMS-22 
condition values*RMS-24 
control block input fields*RMS-23 
control block output fields*RMS-23 
requirements • RMS-23 
DNA (default name address) argument *B-5 
DNM (default name) argument *B-3 
DNM (default name) field *4-4 
DNM (default name) keyword 

specifying FAB$L_DNA and FAB$B_DNS fields 
from VAX MACRO* 5-9 
DNS (default name size) argument *B-5 
DUP (duplicate) option 

to XAB$B_FLG field • B-21 
Duplicate key 
examples* 7-7 
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Duplicate key (cont'd.) 

incompatibility between VAX RMS and 
RMS-11*11-8 
insertion order*RMS-69 
retrieving records *7-7 


E 


EDT argument *B-17 
End-of-file field in XABFHC 
See XAB$L_EBK field 
End-of-file mark 

positioning for user file open option *5-17 
End-of-file option 

See RAB$V_EOF option 
end-of-file positioning • RMS-5 
Enter service*RMS-26 

condition values • RMS-27 
control block input fields • RMS-27 
control block output fields • RMS-27 
requirement for NAM block fields*RMS-27 
Erase service*RMS-29 
alternative • RMS-30 
condition values*RMS-31 

See also Completion status codes 
control block input fields*RMS-30 
control block output fields • RMS-30 
requirements for using*RMS-30 
use restriction • RMS-30 
Error completion routine *2-5 
Error status code *2-5 

from invalid control blocks *2-6 
Escape sequence 

using from terminal devices*RMS-46 
ETO (extended terminal operation) option • RMS-46 
Event flag 

for synchronous operations*2-7 
Executive-mode (PSL$C_EXEC) constant 
for CHAN_MODE subfield *5-5 
Expanded string 
requesting • 6-2 

Expanded string area address (ESA) 
program example *4-12 
Expanded string area address field 
See NAM$L_ESA field 
Expanded string length field 
See NAM$B_ESL field 
Expanded string size field 
See NAM$B_ESS field 


Expiration date field 

See XAB$Q_EDT field 
Extended attribute block 
See XAB block 

Extended attribute block address field 
See FAB$L_XAB field 
See RAB$L_XAB field 
Extended terminal operation option 
See RAB$V_ETO option 
Extend service*RMS-32 
condition values*RMS-33 
control block input fields • RMS-33 
control block output fields*RMS-33 
requirements • RMS-33 
use restriction • RMS-32 
XAB overrides*RMS-33 


F 


$FAB 

argument categories • B-3 
FAB *5-1 

argument categories* 1-2 
description* 1-2 
requirements for* 5-2 
summary of fields • 5-1 
FAB$B_BID field *5-3 
FAB$B_BKS field *5-3 

considerations for calculating • 5-4 
default logic*5-4 
limitation for RMS-11 • 5-3 
performance considerations*5-4 
selecting default size for indexed files *5-4 
variations for XABs*5-4 
FAB$B_BLN field *5-4 
FAB$B_DNS field *5-9 

specifying default file specification • 5-2 
FAB$B_DNS fields*B-3 
FAB$B_FAC field *5-9 

comparing with FAB$B_SHR • 5-9 
for specifying sharing options *4-1 
interdependency with FAB$B_SHR field *5-27 
options* 5-10 

permitting services access *5-10 
use with FAB$B_SHR* 5-9 
FAB$B_FNS field *5-12 

specifying primary file specification • 5-2 
FAB$B_FSZ field *5-17 
FAB$B_ORG field • 5-22 
options* 5-22 
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FAB$B_ORG field (cont'd.) 

use by various services • 5-22 
FAB$B_RAT field *5-22 
default logic *5-22 
options *5-22 
FAB$B_RFM field *5-24 
keywords • 5-24 
options* 5-24 
FAB$B_RTV field *5-25 
FAB$B_SHR field *5-26 

comparing option names with file access optio 
names* 5-26 

conflict with FAB$B_FAC field • 5-26 
default logic *5-27 
for specifying sharing options *4-1 
interdependency with FAB$B_FAC field *5-27 
option naming convention • 5-26 
options *5-26 
FAB$C_FIX option • 5-24 
FAB$C_STMCR option *5-24 
FAB$C_STMLF option *5-24 
FAB$C_STM option *5-24 
FAB$C_UDF option *5-24 
FAB$C_VAR option *5-25 
FAB$C_VFC option *5-25 
FAB$L_ALQ 

setting at run time *3-5 
FAB$L_ALQ field *5-3 
as output field*5-3 
functional variations for XABs*5-3 
use with Create service *5-3 
use with Extend service *5-3 
use with Open service *5-3 
FAB$L_CTX field *5-6 
FAB$L_DEV field*5-7 
bits listed*5-7 
FAB$L_DNA field*5-8, B-3 
components listed *5-8 
specifying default file specification*5-2 
FAB$L_FNA field*5-11 

specifying primary file specification • 5-2 
FAB$L_FOP field *5-12 
options* 5-13 
FAB$L_MRN field*5-19 

consequence of exceeding • 5-20 
FAB$L_NAM field*5-21 
FAB$L_SDC field *5-26 

comparing with FAB$L_DEV field *5-26 
FAB$L_STS field *5-28 

handling for ACL error status* 12-3 
FAB$L_STV field *5-28 
FAB$L_XAB field*5-28 
uses listed • 5-28 


FAB$V_BIO bit 

for specifying I/O mode *4-25 
FAB$V_BIO option *5-10 
FAB$V_BLK option *5-22 
FAB$V_BRO 

use for sharing files *5-27 
FAB$V_BRO option *5-10 
FAB$V_CBT 

precedence over FAB$V_CTG • 5-13 
FAB$V_CBT bit 

as service output *5-12 
FAB$V_CBT option *5-13 
FAB$V_CHAN_MODE subfield 
list of values*5-5 
setting from MACRO *5-6 
FAB$V_CIF option *5-15 

precedence over FAB$V_SUP option *5-15 
FAB$V_CR option • 5-22 

restriction against use with FAB$V_FTN and 
FAB$V_PRN options* 5-22 
FAB$V_CTG 

subordinate to FAB$V_CBT *5-13 
FAB$V_CTG bit 

as service output *5-12 
FAB$V_CTG option *5-13 
FAB$V_DEL bit 

requirement for Delete service *4-22 
FAB$V_DEL option *5-10 
FAB$V_DFW option *5-14 

exception to use of global buffers *5-18 
FAB$V_DLT option *5-15 

qualified use by Close service*RMS-2 
use with FAB$V_SCF or FAB$V_SPL option* 
5-15 

FAB$V_FTN option • 5-23 

restriction against use with FAB$V_CR and 
FAB$V_PRN options* 5-22 
FAB$V_GET access option *5-9, 5-11 

use with block I/O operations*5-10, 5-11 
FAB$V_GET sharing option *5-27 
FAB$V_LNM_MODE field *5-19 
values listed*5-19 
FAB$V_MSE 

enabling multiple RABs* RMS-5 
for global buffer cache *5-27 
FAB$V_MSE option • 5-26 

requirement for read-only buffer cache *5-19 
use with other options *5-27 
FAB$V_MXV option *5-15 
FAB$V_NAM option *5-15 
FAB$V_NEF option *5-16 
FAB$V_NFS option *5-17 
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FAB$V_NFS option (cont'd.) 

relationship to CHAN_MODE subfield*5-5 
FAB$V_NIL bit 

requirement for block 1/0*4-24 
FAB$V_NIL option *5-27 

effect on specifying user file open option *5-17 
precedence over other options *5-27 
FAB$V_OFP option *5-15 
FAB$V_POS option *5-16 

subordinate to FAB$V_RWO option *5-16, 
5-17 

FAB$V_PRN option *5-23 

restriction against use with FAB$V_FTN and 
FAB$V_CR options* 5-22 
FAB$V_PUT access option *5-9, 5-11 
use with block I/O operations*5-10 
FAB$V_PUT sharing option *5-27 
FAB$V_RCK bit 

as service output *5-12 
FAB$V_RCK option *5-14 
restricted use *5-14 
FAB$V_RWC option *5-16 
FAB$V_RW0 option *5-16 

precedence over FAB$V_P0S option *5-16, 
5-17 

FAB$V_SCF option *5-15 

qualified use by Close service*RMS-2 
use restriction *5-16 
FAB$V_SHRDEL option *5-27 
FAB$V_SHRGET option 

for global buffer cache *5-27 
requirement for read-only buffer cache *5-19 
FAB$V_SPL option *5-16 

qualified use by Close service*RMS-2 
FAB$V_SQ0 

prohibiting random access • RMS-45 
FAB$V_SQ0 option *5-14 
FAB$V_SUP option *5-15 

subordinate to FAB$V_CIF option *5-15 
FAB$V_TEF option *5-14 

restriction to sequential files *5-14 
FAB$V_TMD 
option 

inhibiting automatic Create*RMS-26 
FAB$V_TMD option *5-16 

precedence over FAB$V_TMP option *5-16 
FAB$V_TMP option *5-16 

inhibiting automatic Create • RMS-26 
subordinate to FAB$V_TMD option *5-16 
FAB$V_TRN option 

in file access field *5-11 

requirement for truncate-on-put operation • 7-16 


FAB$V_UF0 

effect on internal structures • 5-19 
FAB$V_UF0 option *5-17 

relationship to CHAN_M0DE subfield *5-5 
FAB$V_UPD bit 

requirement for Update service *4-24 
FAB$V_UPD option *5-11,5-27 

requirement for implementing update-if option* 
7-16 

FAB$V_UPI bit 

requirement for block 1/0*4-24 
FAB$V_UPI option *5-27 
reqirement for setting *5-27 
requirement for user file open option *5-17 
FAB$V_WCK bit 

as service output *5-12 
FAB$V_WCK option *5-14 
restricted use *5-14 
FAB$W_BLS field *5-5 
limitation* 5-5 

requirements for RMS-11 compatibility • 5-5 
setting • 5-5 

FAB$W_DEQ field • 5-4, 5-6 
default logic* 5-6 
overriding default *5-7 
FAB$W_GBC field *5-18 
as output • 5-18 
changing *5-18 
clearing *5-18 
overriding default *5-18 
FAB$W_IFI field *5-19 
FAB$W_MRS field • 5-20 
as output *5-20 
summary • 5-20 

use with fixed-length records *5-20 
use with variable-length records *5-20 
$FAB_ST0RE 

argument categories • B-5 
FAB argument requirement • B-5 
$FAB_STORE macro *B-4 
run-time arguments*B-5 
$FAB macro*B-2 
FAC (file access) field • B-3 
Fast delete option 

See RAB$V_FDL option 
FDL$PARSE • 4-9 
FDL$RELE ASE • 4-9 
FDL Editor 

as alternative to multiple XABs in example *4-9 
Field length 

identifier in symbolic name *2-3 
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File 

characteristics argument for FAB* 1-2 
organizations supported by VAX RMS* 1-1 
specification argument for FAB* 1-2 
File access block 
See FAB 

File access block address field 
See RAB$L_FAB field 
File access field 

See FAB$B_FAC field 
File component descriptor 
address field *6-3 
example *6-3 
field value logic *6-3 
list of • 6-3 
size field *6-3 
suggested use of *6-3 
File Definition Language Editor 
See FDL Editor 
File extension 

using Extend service • RMS-33 
File header characteristic extended address block 
See XABFHC block 
File header characteristic XAB 
See XABFHC 
File identification field 
See NAM$W_FID field 
File name address descriptor 
See NAM$L_NAME 
File name address field 
See NAM$L_NAME field 
File name length field 

See NAM$B_NAME field 
File name size descriptor 
See NAM$B_NAME 
File name status bits 
See NAMSL—FNB field 
File name string 

component parts *4-10 
File name string addressf FAB$L_FNA) field 
how used to specify file name string *4-10 
File name string size (FAB$B_FNS) field 
how used to specify file name size *4-10 
File organization and record format field 
See XAB$B_RFO field 
File organization field 
See FAB$B_ORG field 
File owner group number field 
See XAB$W_GRP field 
in XABPRO field* 12-4 
File owner member number field 
See XAB$W_MBM field 


File positioning 

effect on shared files*RMS-6 
File-processing 

VAX RMS services listed *3-3 
File-processing option 
categories listed *5-12 
File-processing option bit 
naming convention • 5-12 
File-processing option bits 
as service output *5-12 
File-processing options field 

See FAB$I_FOP field 

File protection field 

See XAB$W_PR0 field 
File protection option field 

See XAB$B_PROT_OPT field 
File protection XAB 
See XABPRO 
File section 

defining in context of multiple volumes*RMS-53 
File sharing 

conditions listed *5-9 
features provided by VAX RMS* 1-1 
File sharing field 

See FAB$B_SHR field 
File specification 

component descriptors *6-2 
default requirements *4-10 
how handled by Search service *4-10 
parsing • RMS-63 

File specification string address *4-10 
File specification string address field 
See FAB$L_FNA field 
File specification string size *4-10 
File specification string size field 
See FAB$B_FNS field 
File type address descriptor 

See NAM$I_TYPE 

File type address field 

See NAM$I_TYPE field 

File type length field 

See NAM$B_TYPE field 
File type size descriptor 
See NAM$B_TYPE 
File version address descriptor 

See NAM$I_VER 

File version address field 

See NAM$I_VER field 

File version length field 
See NAM$B_VER field 
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File version limit field 

See XAB$W_VERLIMIT field 
File version size descriptor 
See NAM$B_VER 
Fill level 

comparing primary key and alternate keys* 11-9 
Find service*RMS-35 
capabilities • RMS-36 
condition values*RMS-38 
control block input fields*RMS-36 
control block output fields • RMS-38 
First data bucket start virtual block number field 
See XAB$L_DVB field 
First free byte field 

See XAB$W_FFB field 
Fixed-length control area size field 
See FAB$B_FSZ field 
Fixed-length header control size field 
See XAB$B_HSZ field 
Fixed-length record format option 
See FAB$C_FIX option 
Flush service*RMS-40, RMS-41 
condition values • RMS-41 

See also Completion status codes 
control block input fields*RMS-41 
control block output fields • RMS-41 
FNA argument *B-5 
FNM argument *B-3 
FNM keyword 

for specifying FAB$L_FNA and FAB$B_FNS 
fields from VAX MACRO *5-11 
FNS argument*B-5 
FOP (file options) field *B-3 

FORTRAN carriage control option FAB$V_FTN 
option 

FORTRAN carriage control option list *5-23 
Free service • RMS-42 

condition values*RMS-43 

control block input and output fields*RMS-43 


G 


$Get macro 

program example *4-17 
Get option 

See FAB$V_GET option 
Get service*RMS-44, RMS-50 

applicable access modes*RMS-44 
condition values*RMS-50 

See also Completion status codes 


Get service (cont'd.) 

control block input fields • RMS-47 
control block output fields • RMS-50 
requirement for user record area*RMS-47 
returning terminator character for terminal 
input* RMS-46 

return status for various file access methods • 
RMS-5 

using input from mailbox devices • RMS-47 
using stream input*RMS-45 
using terminal input*RMS-45 
using the RAB$I—STV field for additional status 
information* RMS-47 
Get sharing option 

See FAB$V_GET sharing option 
Global buffer 

determining number of *5-18 
Global buffer count field 
See FAB$W_GBC field 


H 


HDR1 labels 

accessing from XAB$B_MTACC field* 12-5 
Highest virtual block field 
See XAB$L_HBK field 


i 


I/O mode 

how to switch for sequential files *4-26 
procedure for delaying decision until stream 
connection* 4-25 

when mode switching allowed *4-25 
Index bucket area number (IAN) 
program example *4-9 
Index bucket area number field 
See XAB$B_IAN field 
Index bucket fill size (IFL) 
program example *4-9 
Index bucket fill size field 
See XAB$W_IFL field 
Index bucket size field 
See XAB$B_IBS field 
Indexed file 

use of areas in • 4-8 
Index level 

comparing primary key and alternate keys* 1 1-9 
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Initialization macro 

advantages described • 3-7 
example *3-5 
functions* 3-1 
multiple bit field *3-5 
placement guidelines*3-7 
using *3-6 
Inserting record 

program example *4-17 
Internal file identifier field 
See FAB$W_IFI field 
Internal stream identifier field 
See RAB$W_ISI field 
IO$M_NOW modifier 

for Get and Put services*7-14 
Item list* 15-1 

guidelines for supplying* 15-1 
Item list address field 

See XAB$L_ITMLST field 
Item list length field 

See XAB$W_ITMLST_LEN field 


Key of reference 

establishing • RMS-45 
Key of reference field 
See RAB$B_KRF field 
See XAB$B_REF field 
Key option 

comparing primary and alternate keys* 11-6 
Key options flag field 
See XAB$B_FLG field 
Key position field 

See XAB$W_POSO through XAB$B_P0S7 
field 

Key size field 

See RAB$B_KSZ field 

See XAB$B_SIZO through XAB$B_SIZ7 field 
Key string buffer 

program example *4-17 
Key string descriptor 
program example *4-17 
Key string length 

program example *4-17 



L 


Key 

defining as simple or segmented* 11-11 
determining match method *7-5 
example of use in finding and deleting a record* 
4-22 

example of use in updating a record *4-23 
match methods *7-4 
selecting path *4-13 
size restriction for string type* 11-13 
specifying a generic match *7-5 
specifying an approximate generic match *7-5 
specifying an approximate match *7-5 
specifying exact match *7-5 
Key buffer address field 
See RAB$L_KBF field 
Key definition extended address block 
See XABKEY block 
Key definition XAB 
See XABKEY 

Key greater than or equal search option 
See RAB$V_EQNXT option 
Key greater than search option 
See RAB$V_NXT option 
Key name buffer address field 
See XAB$L_KNM field 


Length field 

using to indicate constant (keyword) value *2-4 
using to indicate mask or bit offset *2-3 
Level of root bucket field 
See XAB$B_LVL field 
LIB$GET_INPUT 

example of use in VAX RMS program *4-12 
LIB$PUT_OUTPUT 

example of use in VAX RMS program *4-12 
LIBSSIGNAL (or LIB$STOP) 

using to signal VAX RMS errors *2-6 
Limit option 

See RAB$V_LIM option 
Load (LOA) record option 
program example *4-9 
Load option 

See RAB$V_LOA option 
Locate mode 

comparing with move mode for buffer handling* 
7-14 

Locate mode option 

See RAB$V_LOC option 
Location field in XABALL 
See XAB$I_LOC field 
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Lock record for read option 
See RAB$V_REA option 
Lock record for write option 
See RAB$V_RLK option 
Logical name translation 

requirements for parsing *4-10 
Logical name translation access mode field 
See FAB$V_LNM_MODE field 
Longest record length field 
See XAB$W_LRL field 
Lowest level of index area number field 
See XAB$B_LAN field 



Macro 

applicable VAX MACRO syntax rules *3-5 
arguments for service completion routines* 

3-11 

control block initialization • 3-1 

for defining VAX RMS symbol *3-1 

for initializing VAX RMS control blocks *3-1 

for invoking VAX RMS at run time *3-1 

for VAX RMS control block store *3-1 

library location *3-2 

names and control blocks *3-2 

naming conventions*3-2 

rules applicable to VAX RMS programming • 3-6 
service* 3-1 

service macro format rules *3-11 
syntax applicable to VAX RMS *3-1 
using • 3-6 

VAX RMS types *3-1 
Macro field 

example of initializing • 3-5 
setting at run time *3-5 
Magnetic tape accesibility field 
See XAB$B_MTACC field 
Manual unlock option 
See RAB$V_ULK option 
MAXBUF system parameter 

limiting size of user's ACL buffer* 12-3 
Maximum record number field 
See FAB$L_MRN field 
Maximum record size field 
See FAB$W_MRS field 
see MRS field 

Maximum record size field in XABFHC 
See XAB$W_MRZ field 


Maximum version option 
See FAB$V_MXV option 
Minimum record length field 
See XAB$W_MRL field 
in XABKEY • 11-10 
Mixed I/O 

precautions listed *4-26 
Mode switching 

when permitted *4-25 
MRS (maximum record size) field 
program example *4-4 
Multiblock count field 
See RAB$B_MBC field 
Multibuffer count field 
See RAB$B_MBF field 
Multiple argument 

delimiting in control block fields *3-5, 3-7 
specifying in control block fields *B-3 
Multiple key 

example of use with Close service *4-13 
performance cost of using* 11-13 
recommended number* 11-13 
Multiple-key indexed file 
creating *4-5 
Multiple record stream 
with block 1/0*4-26 
Multistream access option 
See FAB$V_MSE option 


N 


NAM 

summary of fields*6-1 
using from higher-level language *6-2 
using from VAX MACRO *6-2 
NAM (name) block *6-1 
NAM$B_BID field *6-4 
NAM$B_BLN field *6-4 
N AM$B_DEV • 6-3 
NAM$B_DEV field *6-4 
NAM$B_DIR • 6-3 
NAM$B_DIR field *6-4 
NAM$B_ESL field *6-5 
NAM$B_ESS field *6-5 
NAM$B_N AME • 6-3 
NAM$B_NAME field *6-7 
N AM$B_NODE • 6-3 
NAM$B_N0DE field • 6-7 
NAM$B_N0P field *6-7 
options listed *6-7 
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NAM$B_RSL field*6-9 
NAM$B_RSS field • 6-9 
NAM$B_TYPE • 6-3 
NAM$B_TYPE field *6-9 
N AMSB—VER • 6-3 
NAM$B_VER field *6-9 
NAM$L_DEV • 6-3 
NAM$L_DEV field *6-4 

N AM$I_DIR • 6-3 

NAM$L_DIR field *6-4 

NAM$I_ESA field *6-5 

NAM$L_FNB field *6-6 
NAM$L_FNB Status Bit 
listing *6-6 
NAM$L_NAME*6-3 
NAM$L_NAME field*6-7 

N AM$I_NODE • 6-3 

NAM$I_NODE field *6-7 

NAM$I_RLF field *6-8 

NAM$L_RSA field *6-8 
N AM$L _TYPE *6-3 
NAM$L_TYPE field *6-9 

NAM$I_VER* 6-3 

NAM$I_VER field *6-9 

NAM$I_WCC field *6-9 

NAM$T_DVI field *6-5 

NAM$V_CNCI_DEV • 6-6 

NAM$V_DIR_LVLS • 6-6 
N AMS V_EXP_DEV • 6-6 
N AM$V_EXP_DIR • 6-6 
N AM$V_EXP_N AME • 6-6 
NAM$V_EXP_TYPE • 6-6 
N AM$V_EXP_VER • 6-6 
N AM$V_GRP_MBR • 6-6 
N AM$V_HIGHVER • 6-6 
NAM$V_LOWVER • 6-6 
NAM$V_NOCONCEAL option • 6-7 
N AM$V_NODE • 6-6 
NAM$V_PPF • 6-6 
NAM$V_PWD option • 6-7 
NAM$V_QUOTED • 6-6 
N AM$V_ROOT_DIR • 6-6 
N AMS V_SE ARCH _LIST • 6-6 
NAM$V_SRCHXABS option *6-8 
NAM$V_SYNCHK option *6-8 
NAM$V_SYNCK option 

using for Parse service without l/0*RMS-i 
N AM$V_WILD_GRP • 6-6 
N AM$V_WILD_MBR • 6-6 
NAM$V_WILD_NAME • 6-6 
N AMS V_WILD_SFD 1 *6-6 
NAM$V_WILD_TYPE • 6-7 


N AM$V_WILD_UFD • 6-7 
N AM$V_WILD_VER • 6-7 
N AM$V_WILDC ARD • 6-6 
NAM$W_DID field *6-4 
NAM$W_FID field *6-5 
$NAM_STORE macro* B-7 
argument categories • B-7 
comparing with $NAM macro*B-7 
NAM$T_DVI argument*B-7 
NAM$W_DID argument*B-7 
NAM$W_FID argument*B-7 
requirements • B-7 
NAM block option 

See FAB$V_NAM option 
Name block 

See NAM block 
Name block address field 

See FABSI_NAM field *5-21 

Name block options field 
See NAM$B_NOP field 
Name control block 

See NAM (name) block 
Naming convention 
macros • 3-2 
VAX RMS services *3-3 
$NAM macro *B-6 

argument categories • B-6 
NBP (next block pointer) • 4-27 
default for block transfer • 7-2 
for doing block 1/0*4-27 
functions listed *4-27 
NETWORK_BLOCK_COUNT qualifier 

for specifying maximum record size • 5-21 
Next block pointer 

See NBP (next block pointer) 

Next key search option 
See RAB$V_NXT option 
Next or equal key search option 
See RAB$V_EQNXT option 
Next Volume service • RMS-52 
condition values*RMS-54 
control block input and output fields • RMS-53 
flush logic*RMS-53 
input logic sequence*RMS-53 
output logic sequence • RMS-53 
requirements for using • RMS-53 
Next XAB address field 

See XABSI_NXT field 

Next XAB address field in XABKEY 
See XAB$L_NXT field 
Next XAB address field in XABPRO 
See XAB$I_NXT field 
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Next XAB addrss in XABFHC 
See XAB$L_NXT field 
Next XAB field 

See XAB$L_NXT field 
Next XAB field in XABRDT 

See XABSI_NXT field 

Next XAB field in XABSUM 
See XAB$L_NXT field 
Node name address descriptor 
See NAM$L_NODE 
Node name address field 

See NAM$I_NODE field 

Node name length field 
See NAM$B_NODE field 
Node name size descriptor 
See NAM$B_NODE 
No lock option 

See RAB$V_NLK option 
Nonexistent record option 
See RAB$V_NXR option 
Non-file-structured option 
See FAB$V_NFS option 
NOP field 

specifying multiple values *B-6 
No sharing option 

See FAB$V_NIL option 
Not end-of-file option 
See FAB$V_NEF option 
Null character field 

See XAB$B_NUL field 
Number of allocation areas field 
See XAB$B_NOA field 
Number of key segments field 
See XAB$B_NSG field 
Number of keys field 
See XAB$B_NOK field 
Number sign 

requirement for in control store macro*3-8 
NXTVOL service 

See Next Volume service 


o 


SOPEN macro 

expansion of *3-10 
for invoking the open service *4-1 
using in example • 3-10, 3-11 
Open service*RMS-55 

condition values*RMS-61 


Open service (cont'd.) 

contrasted with Parse and Search services* 
4-10 

control block input fields • RMS-56 
control block output fields • RMS-58 
function *4-1 
invoking • 4-5 
NAM input fields • RMS-60 
NAM output fields*RMS-60 
program example *4-2 
requirements for using*RMS-56 
Option 

specifying by symbolic bit offset *2-3 
Optional argument 

to VAX RMS service *3-10 
Output file parse option 
See FAB$V_OFP option 
Output record buffer address field 
See RAB$L_RBF field 


p 


Packed decimal byte 

structure for key type* 11-5 
Packed decimal string 
as key type* 11-5 
SPARSE macro 

for processing wildcard characters • 4-10 
Parse service • RMS-63 
condition values • RMS-65 
control block input fields • RMS-64 
control block output fields • RMS-65 
preparing for file search *4-10 
preparing for wildcard character processing* 
RMS-63 

program example *4-10 
requirements for using*RMS-64 
Path to file 

file specification string address *4-10 
file specification string size *4-10 
Performance 

improving with SHR argument • 4-15 
Print format option 

See FAB$V_PRN option 

Print format options for VFC records with 2-byte 
control area • 5-23 
Program 

using wildcard characters • 4-12 
Program execution mode 

using to call VAX RMS services *2-7 
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Program interface 
to VAX RMS *2-1 
Programming language 

using control blocks with*2-1 
Prologue field 

See XAB$B_PROLOG field 
Prologue level*RMS-16 
Prologue version number field 
See XAB$W_PVN field 
Prompt buffer address field 
See RAB$L_PBF field 
Prompt buffer size field 
See RAB$B_PSZ field 
Prompt option 

See RAB$V_PMT option 
Protection extended address block 
See XABPRO block 

PSL$C_EXEC channel access mode protection 
option • 5-5 

PSL$C_SUPER channel access mode protection 
option* 5-5 

PSL$C_USER channel access mode protection 
option *5-5 

Purge type-ahead option 
See RAB$V_PTA option 
$Put macro 

program example *4-17 
Put service*RMS-67 

caution relative to use of record locking a 
shared file* RMS-69 
condition values • RMS-71 

See also Completion status codes 
control block input fields*RMS-69 
control block output fields • RMS-70 
inserting records by sort order*RMS-68 
inserting records into indexed files*RMS-68 
inserting records into relative files*RMS-68 
inserting records into sequential files*RMS-68 
inserting records with duplicate keys*RMS-69 
record-processing options *7-15 
requirements for using*RMS-69 
update-if logic*RMS-69 
using RAB$V_TPT option • RMS-68 
using RAB$V_UIF option • RMS-68 
using with mailboxes*RMS-68 
using with stream format files*RMS-68 
Put service option 

See FAB$V_PUT option 
Put sharing option 

See FAB$V_PUT sharing option 


Q 


$QIO system service 

use in VAX RMS I/O operation • 2-7 


R 


RO 

use by control block store macros *3-8 
use in asynchronous operations • 2-5 
RAB 

described in context of example *4-4 
RAB (record access block) 
arguments* 1-4 
description* 1-4 
general description • 7-1 
summary of fields • 7-1 
RAB$_V_WAT option 

use with timeout option for record locking • 
7-17 

RAB$B_BID field *7-2 
RAB$B_BLN field • 7-3 
RAB$B_KRF field • 7-4 

for selecting key path *4-13 
for various services *7-4 
RAB$B_KSZ field *7-4 
DECnet requirement • 7-4 
key size vs. data types *7-4 
shared offset • 7-4 
use with limit option *7-13 
use with search key option*7-12, 7-13 
RAB$B_MBC field *7-5 
default logic*7-5 
performance benefit *7-5 
use restriction • 7-5, 7-6 
RAB$B_MBF field *7-6 
default logic *7-6 
performance benefit *7-6 
use restriction*7-6 
use with read-ahead option *7-15 
use with write-behind option *7-15 
values for various organizations*7-6 
RAB$B_PSZ field • 7-7 
shared offset • 7-7 
RAB$B_RAC field • 7-7 
options* 7-7 
use restriction *7-7 
RAB$B_TMO field *7-19 

for various record functions* 7-19 
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RAB$B_TMO field (cont'd.) 

requirement for RAB$V_TMO option*7-19 
use with RAB$V_TMO option for mailbox 
service* 7-14 

use with timeout option for terminal operation • 
7-18 

RAB$C_KEY option *7-8 
RAB$C_RFA option *7-8 
RAB$C_SEQ option *7-7 
RAB$L_BKT field *7-2 
as output*7-2 
use with block I/O*7-2 
RAB$L_CTX field *7-3 
RAB$L_FAB field *7-3 
RAB$L_KBF field *7-3 
shared offset*7-3 
use with limit option *7-13 
use with RAB$B_KSZ* 7-3 
use with search key option *7-12, 7-13 
RAB$L_PBF field *7-6 

requirement for carriage control *7-6 
RAB$L_RBF field *7-8 
RAB$L_RHB field *7-9 

buffer size compatibility with FAB$B_FSZ* 7-9 
default logic*7-9 
use by various services *7-9 
use restriction • 7-9 
RAB$L_ROP field *7-9 
options listed *7-10 
specifying key match method *7-5 
RAB$L_STS field *7-19 
RAB$L_STV field *7-19 
RAB$L_UBF field*7-20 
buffer logic*7-20 
RAB$L_XAB field *7-20 

requirement for using XABTRM* 15-1 
RAB$V_ASY option *7-11, 7-14 
use restriction*7-14 
RAB$V_BI0 option *7-11 
RAB$V_CCO option *7-17 
RAB$V_CVT option *7-17 
RAB$V_EOF option *7-11 
RAB$V_EQNXT option *7-12 
examples* 7-12 

specifying key match method *7-5 
RAB$V_ETO option 

requirement for using XABTRM* 15-1 
RAB$V_FDL option *7-14 

performance considerations*7-14 
use restriction*7-14 
RAB$V_KGE option 

See RAB$V_EQNXT option 


RAB$V_KGE option (cont'd.) 

See RAB$V_NXT option 
RAB$V_LIM option *7-13 
RAB$V_LOA option *7-13 
determining fill size* 11-9 
use restriction* 11-3, 11-9 
RAB$V_LOC option *7-14 
use restrictions* 7-15 
RAB$V_NLK option *7-16 

precedence over RAB$V_ULK* 7-16 
RAB$V_NXR option *7-16 

output from Get service *7-16 
relevent completion codes *7-16 
use restriction • 7-16 
RAB$V_NXT option *7-13 
examples* 7-14 

specifying key match method *7-5 
RAB$V_PMT option *7-18 
RAB$V_PTA option *7-18 
RAB$V_RAH option *7-11,7-15 
default logic*7-15 
use restriction*7-15 
RAB$V_REA option *7-16 
use restriction*7-16 
RAB$V_RLK option *7-16 

precedence over RAB$V_REA *7-17 
RAB$V_RNE option *7-18 
RAB$V_RNF option *7-18 
RAB$V_RRL option *7-17 
RAB$V_TMO option *7-14, 7-17, 7-18 
for immediate mailbox service *7-14 
RAB$V_TPT option *7-16 
use restriction *7-16 
using with Put service • RMS-68 
RAB$V_UIF option *7-16 
effects on Put service *7-16 
use restriction for indexed files *7-16 
using with Put service • RMS-68 
RAB$V_ULK option *7-17 
affected services*7-17 
subordinate to RAB$V_NLK • 7-17 
RAB$V_WAT option *7-17 

precedence over other options *7-18 
use with the RAB$V_TMO option *7-17 
RAB$V_WBH option *7-11,7-15 
default logic*7-15 
use restriction *7-15 
RAB$W_ISI field *7-3 
RAB$W_RFA field • 7-8 

additional symbolic offsets *7-8 
example* 7-9 
guidelines for using *7-8 
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RAB$W_RSZ field *7-18 
for various services • 7-18 
operational notes listed*7-19 
RAB$W_STVO offset 

alternate access to RAB$L_STV field *7-19 
RAB$W_STV2 offset 

alternate access to RAB$L_STV field *7-19 
RAB$W_USZ field • 7-20 
recommended value *7-20 
use with block 1/0*7-20 
$RAB_ST0RE macro *B-1 1 
argument categories *B-12 
comparing with $RAB macro *B-1 1 
requirements • B-12 
RFA argument • B-12 
$RAB macro*B-9 

argument categories • B-9 
RAT (record attribute) field • B-3 
RBF (record buffer) field *4-5 
RDT (revision-date-time) argument • B-17 
Read ahead option 

See RAB$V_RAH option 
Read check option 

See FAB$V_RCK option 
Read-no-echo option 

See RAB$V_RNE option 
Read no filter option 

See RAB$V_RNF option 
Read-only global buffer cache 
specifying • 5-27 
Read regardless of lock option 
See RAB$V_RRL option 
Read service*RMS-72 

condition values • RMS-73 
control block input fields • RMS-73 
control block output fields • RMS-73 
requirements for using*RMS-73 
Record 

access modes supported by VAX RMS* 1-1 
formats supported by VAX RMS* 1-1 
requirements for reading or writing in a file* 
4-13 
retrieving 

VAX RMS program example *4-17 
Record access block 
See RAB 

Record access field 
See RAB$B_RAC field 
Record attribute field 
See FAB$B_RAT field 
Record attributes field in XABFHC 
See XAB$B_ATR field 


Record buffer field 
See RBF field 
Record file address field 
See RAB$W_RFA field 
Record format field 
See FAB$B_RFM field 
Record header buffer field 
See RAB$L_RHB field 
Record I/O 

how to execute • 4-26 

Record locking record-processing options *7-16 
Record-processing 

VAX RMS services listed *3-3 
Record-processing macro 
format example *3-11 
Record-processing option 
for Connect service *7-11 
Record-processing options field 
See RAB$L_R0P field 
Record size field 

See RAB$W_RSZ field 
See RSZ field 
Record stream 

in the context of a RAB *7-1 
Register 

saving when making call *2-4 
Register 0 
See RO 

Related file identification field in XABALL 
See XAB$W_RFI field 
Related file NAM block address field 
See NAM$L_RLF field 
Relative file 

determining record length *5-20 
Relative volume number field 
See XAB$W_V0L field 
Release service*RMS-75 
condition values*RMS-76 
control block input and output fields*RMS-76 
Remove service*RMS-77 

caution against mixing with Search service* 
RMS-78 

comparing with Erase service • RMS-77 
condition values • RMS-79 
control block input fields • RMS-78 
control block output fields*RMS-79 
improving performance*RMS-78 
requirements for using*RMS-77 
use with wildcard characters and search lists* 
RMS-78 
SRENAME 

noting format difference*3-11 


Index—16 





Index 


Rename service*RMS-80, RMS-81 

alternative to specifying arguments to 
SRENAME macro*RMS-81 
condition values*RMS-83 
control block input fields*RMS-81 
control block output fields • RMS-82 
exception in argument list *2-5 
format *3-11 

indicating successful completion *4-17 
program example *4-15 
requirements for using*RMS-81 
Reserved event flag 

use by VAX RMS *2-7 
Restriction 

calling VAX RMS *2-7 
Resultant string 
requesting *6-2 

Resultant string area address field 
See NAM$L_RSA field 
Resultant string area size field 
See NAM$B_RSS field 
Resultant string length field 
See NAM$B_RSL field 
Retrieval window size field 
See FAB$B_RTV field 

Revision date and time extended address block 
See XABRDT block 
Revision date and time field 
See XAB$Q_RDT field 
Revision date and time XAB 
See XABRDT 
Revision field number field 
See XAB$W_RVN field 
Revision number field 
See XAB$W_RVN field 
Rewind on close option 
See FAB$V_RWC option 
Rewind on open option 
See FAB$V_RWO option 
Rewind service*RMS-84, RMS-85 
condition values*RMS-85 
control block input fields* RMS-85 
control block output fields*RMS-85 
use restriction*RMS-85 
RFA (record's file address) field 

as argument to $RAB_STORE macro *B-12 
RFI (related file identification) field 

as argument to SXABALI_STORE macro *B-14 

RMS 

See VAX RMS (Record Management Services) 
RMS-11 

block identifier field limitation • 5-3 


RMS$_OK_LIM success status code *7-13 

RMS$_QIO • 15-2 

RMS—DFNBC 

for specifying default network block count • 
5-21 

SRMSDEF macro 

access to symbolic offset names *2-2 
use in defining VAX RMS macros *3-8 
Root index bucket virtual block field 
See XAB$L_RVB field 
RSZ (record size) field • 4-5 
Run-time 

access options under VAX RMS* 1-2 
implementation of VAX RMS services *4-1 
information to VAX RMS listed* 1-4 
processing environment • 2-1 


s 


Search list 

as alternative to using wildcard characters* 
4-10 

using with Remove service*RMS-78 
$SEARCH macro 

for processing wildcard characters *4-10 
Search option 
synonyms* 7-12 
Search service • RMS-86 
condition values*RMS-88 
control block input fields*RMS-87 
control block output fields • RMS-88 
example of completion code handling *4-12 
program example *4-10 

requirement for preparatory Parse service *4-10 
using with wildcard characters and search lists* 
RMS-87 

Search string translation 

requirements for parsing *4-10 
Secondary device characteristics field 
See FAB$L_SDC field 
Section 14 block 

for key information* 11-1 
Segmented key* 11-11 

restriction against overlapping* 11-11 
Separator 

in symbolic name *2-3 
Sequential only option 
See FAB$V_SQ0 option 
Service macro 
description *3-1 
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Service macro (cont'd.) 

for creating and processing files*4-1 
format • 3-10, 3-11 
listed by type *3-12 
SET FILE command 

for changing global buffer count value *5-18 
SET RMS_DEFAULT command *7-5 
to limit default extension quantity *5-6 
Set system failure exception mode 
See SYSSSETSFM 
Severity code 

in completion status code field *2-5 
S field 

for specifying field length *2-3 
Shared access 

requirement to specify *4-1 
Shared file 

end-of-file positioning • RMS-6 
SHR (file sharing options) field *B-3 
Sign representation 

preference for key type coding* 11-5 
Simple key* 11-11 
Sort order 

establishing* 7-5 
Space service*RMS-90 
condition values*RMS-91 
control block input fields*RMS-91 
control block output fields*RMS-91 
Spool file option 

See FAB$V_SPL option 
Starting logical block number field 
See XAB$L_SBN field 
Stream record format option 
See FAB$C_STM option 
Stream record format with carriage return option 
See FAB$C_STMCR option 
Stream record format with line feed option 
See FAB$C_STMLF option 
STS (status) field 

See also Completion status field 
contents* 2-5 
STV (status value) field 

See also Completion status field 
contents* 2-5 

Submit command file option 
See FAB$V_SCF option 
Success completion routine *2-5 
Summary extended address block 
See XABSUM block 
Summary XAB 
See XABSUM 


Supersede existing file option 
See FAB$V_SUP option 
Supervisor-mode (PSL$C_SUPER) constant 
for CHAN_MODE subfield *5-5 
Symbol definition macro 
description *3-1 
using *3-7 
Symbolic address 

use in locating start of control block *3-7 
Symbolic bit offset 

use in specifying options *2-3 
Symbolic naming exception 
control block *2-3 
Symbolic offset 
control block *2-3 
format • 2-2 

use in locating control block fields *2-2 
SYSSCLOSE 

See CLOSE service 
SYSSCONNECT 

See CONNECT service 
SYS$CREATE 

See CREATE service 
SYSSDELETE 

See DELETE service 
SYSSDISCONNECT 

See DISCONNECT service 
SYSSDISPLAY 

See DISPLAY service 
SYS$ENTER 

See ENTER service 
SYSSERASE 

See ERASE service 
SYSSEXTEND 

See EXTEND service 
SYSSFIND 

See FIND service 
SYSSFLUSH 

See FLUSH service 
SYSSFREE 

See FREE service 
SYSSGET 

See GET service 
SYS$LIBRARY:STARLET.MLB 

as source of VAX RMS macros* 1-1, 3-2 
SYSSNXTVOL 

See NXTVOL service 
SYSSOPEN 

See OPEN service 
SYSSPARSE 

See PARSE service 
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SYS$PUT 

See PUT service 
SYSSQIO 

for additional processing • 5-17 
SYSSREAD 

See READ service 
SYSSRELEASE 

See RELEASE service 
SYSSREMOVE 

See REMOVE service 
SYSSRENAME 

See RENAME service 
SYSSREWIND 

See REWIND service 
SYSSRMSRUNDWN 
See Control routines 
SYSSSEARCH 

See SEARCH service 
SYSSSETDDIR 

See Control routines 
SYSSSETDFPROT 
See Control routines 
SYSSSETSFM 

use in signaling VAX RMS errors *2-6 
SYSSSPACE 

See SPACE service 
SYSSTRUNCATE 

See TRUNCATE service 
SYSSUPDATE 

See UPDATE service 
SYSSWAIT 

See WAIT service 
SYSSWRITE 

See WRITE service 
SYSPRV privilege 

requirement for creating files with different UIC* 
12-7 

System service exception • 2-6 
System service exception generation 
disabling • 2-6 


T 


Terminal extended address block 
See XABTRM block 
Terminal read operation 

related RAB$L_ROP field options* 15-1 
Terminal XAB 
See XABTRM 
T field 

for specifying varying field length *2-3 
Timeout option 

See RAB$V_TMO option 
Timeout period field 
See RAB$B_TMO field 
Total key size field 

See XAB$B_TKS field 
in XABKEY • 11-14 
Truncate at end-of-file option 
See FAB$V_TEF option 
Truncate on put option 

See also RAB$V_TPT option 
Truncate option 

See FAB$V_TRN option 
Truncate service*RMS-95 
condition values • RMS-96 

See also Completion status codes 
control block input fields • RMS-96 
control block output fields • RMS-96 
use restriction • RMS-95 
Type code field 

See XAB$B_COD field 
in XABPRO field* 12-4 
Type code field in XABDAT 
See XAB$B_COD field 
Type code field in XABFHC 
See XAB$B_COD field 
Type code field in XABKEY 
See XAB$B_COD field 
Type code field in XABPRO 
See XAB$B_COD field 
Type code field in XABRDT 
See XAB$B_COD field 
Type code field in XABSUM 
See XAB$B_COD field 
Type code field in XABTRM 
See XAB$B_COD field 


Temporary file delete option 
See FAB$V_TMD option 
Temporary file option 

See FAB$V_TMP option 
Terminal device record-processing option *7-17 


u 


UBF (user buffer) field *4-4 


Index—19 







Index 


UIC (user identification code) 

delimiting in control block fields*3-7 
Undefined record format option 
See FAB$C_UDF option 
Update-if option 

See RAB$V_UIF option 
Update service*RMS-97 
See FAB$V_UPD option 

comparing with Put service for stream format 
files* RMS-98 
condition values*RMS-99 
control block input fields • RMS-98 
control block output fields • RMS-98 
program example *4-22 
requirements for using • RMS-97 
using with indexed files*RMS-98 
Update sharing option 
See FAB$V_UPD option 
User buffer field 

See UBF (user buffer) field 
User context field 

See RAB$L_CTX field 
User-entered reply 

as used in example for selecting key path *4-13 
User file-open option 

See FAB$V_UFO option 
User identification code field 

See XAB$I_UIC field 

User input record area address field 
See RAB$L_UBF field 
User-mode (PSL$C_USER) constant 
for CHAN_MODE subfield *5-5 
User process interlock option 
See FAB$V_UPI option 
User prompt string 

program example *4-17 
User record area size field 
See RAB$W_USZ field 
User size field 

See USZ (user buffer size) field 
USZ (user buffer size) field *4-4 


v 


Variable-length format option 
See FAB$C_VAR option 
Variable-length record 

guidelines for specifying • 5-20 
VAX language 

use with control blocks *2-1 


VAX MACRO 
See Macro 

VAX Procedure and Condition Handling Standard 
for calling VAX RMS services *3-3 
VAX RMS (Record Management Services)* 1-1 
access modes* 1-1 

applicable macro programming rules *3-6 

argument delimiters*3-10 

block I/O processing services *3-5 

calling sequence *2-4 

calling services* 1-1 

control blocks* 1-2 

file organizations* 1-1 

macro capabilities listed *4-1 

passing arguments to* 1-2 

program interface description • 2-1 

record formats* 1-1 

restrictions to calling *2-7 

security features* 1-1 

sequence for using *2-1 

service* 1-2 

supporting file operations* 1-2 
supporting record operations* 1-2 
use of Digital Multinational Character Set *2-7 
use of reserved event flags • 2-7 
VAX RMS (Record Management Services) error 
recommended method for signaling • 2-6 
VAX RMS (Record Management Services) service 
allowable program execution modes for calling* 
2-7 

calling example *3-11 
naming conventions *3-3 
optional arguments*3-10 
VFC record format option 
See FAB$C_VFC option 


w 


SWAIT macro 

format difference *3-11 
Wait option 

See RAB$V_WAT option 
Wait service*RMS-100 

condition values*RMS-101 
control block input and output fields*RMS-100 
Wildcard character 

use with Remove service*RMS-78 
use with Search service *4-10 
Wildcard context field 
See NAM$I_WCC field 
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Wildcard substitution 

specifying the NAM$L_RSA field*6-8 
Write-behind option 

See RAB$V_WBH option 
Write check option 

See FAB$V_WCK option 
Write service*RMS-102, RMS-103 
condition values*RMS-104 
control block input fields • RMS-103 
control block output fields • RMS-103 


x 


XAB$B_AID field • 8-2 
XAB$B_ALN field*8-2 
XAB$B_AOP field • 8-3 
options *8-4 
XAB$B_ATR field* 10-2 
options* 10-2 
XAB$B_BKZ field • 8-4 
as output • 8-5 
default logic *8-4, 8-5 
determining bucket size *8-5 
RMS-11 restriction • 8-4 
size requirements for multiple index areas *8-5 
XAB$B_BKZ field in XABFHC • 10-2 
XAB$B_BLN field *8-5, 9-2, 11-2, 12-4, 13-2, 
14-1, 15-2 

XAB$B_BLN field in XABFHC* 10-3 
XAB$B_C0D field *8-5, 9-3, 11-2, 12-4, 13-2, 
14-1, 15-2 

XAB$B_COD field in XABFHC* 10-3 
XAB$B_DAN field* 11-2 
requirement for* 11-3 
XAB$B_DBS field* 11-3 
XAB$B_DTP field* 11-3 
data formats* 11-5 
data type restrictions *11-4 
options* 11-4 

use with search key option *7-12, 7-13 
value prefixes for sorting *11-4 
XAB$B_FLG 

option allowable combinations listed* 11-8 
XAB$B_FLG field* 11-6, B-21 
options* 11-7 
XAB$B_HSZ field* 10-4 
use restriction • 10-4 
XAB$B_IAN field* 11-8 
conditional usage* 11-8 
indicating index level *8-5 


XAB$B_IBS field* 11-9 
XAB$B_LAN field* 11-10 
indicating index level *8-5 
relationship to XAB$B_AID field* 11-10 
requirement for compatibility with XAB$B_IAN 
field* 11-10 
use restriction* 11-10 
XAB$B_LVL field *11-10 
XAB$B_MTACC field* 12-4 
default logic* 12-5 
valid character codes* 12-5 
XAB$B_NOA field* 14-2 
XAB$B_NOK field* 14-2 
XAB$B_NSG field *11-11 
XAB$B_NUL field* 11-11 
use restrictions* 11-11 
XAB$B_PROLOG field* 11-12 
default logic* 11-12 
service usage* 11-12 
use restriction* 11-12 
XAB$B_PROT_OPT field* 12-6 
XAB$B_REF field *11-12 
XAB$B_RF0 field* 10-5 
values listed • 10-5 

XAB$B_SIZ0 through XAB$B_SIZ7 field* 11-13 
default logic* 11-13 
requirement for being compatible with 

XAB$W_POSO through XAB$B_P0S7 
field* 11-13 

with segmented key* 11-13 
with simple key* 11-13 
XAB$B_TKS field *11-13 
X ABSC—ALL • 8-5 
XAB$C_ALLEN • 8-5 
XAB$C_DAT • 9-3 
XAB$C_DATLEN • 9-2 
XABSC—FHC* 10-3 
XAB$C_FHCLEN • 10-3 
XAB$C_PRO* 12-4 
XAB$C_PROLEN•12-4 

XABSI_ACLBUF field* 12-2 

determining value for Create service* 12-2 
determining value for Open and Display service 
12-2 

handling ACE* 12-2 

XAB$I_ACLCTX field* 12-2 

XAB$I_ACLSTS field* 12-3 

error handling guidelines* 12-3 
use restriction • 12-4 

XABSI_ALQ field *8-3 

XAB$L_DVB field* 11-6 
XAB$L_EBK field* 10-3 
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XAB$L_HBK field • 10-4 

comparing with FABSl_ALQ field* 10-4 

XAB$L_ITMLST field* 15-2 

XAB$I_KNM field* 11-9 

XAB$I_LOC field *8-6 

determining value *8-6 
requirement for alignment option *8-6 

XAB$I_NXT field *8-6, 9-3, 11-11, 12-5, 13-2, 

14-2, 15-2 

XAB$I_NXT field in XABFHC* 10-4 

XAB$I_RVB field* 11-13 

XAB$I_SBN field* 10-5 

XAB$L_UIC field* 12-4, 12-7 

combining the XAB$W_GRP and <XMNM 
fields* 12-7 

order of determining value* 12-7 
setting XAB$W_MBM field* 12-4 
settng XAB$W_GRP field* 12-4 
X AB$M _NODEL • 12-5 
XAB$M_NOEXE • 12-5 
X AB$M_NOREAD • 12-5 
XAB$M_NO WRITE • 12-5 
XAB$M_PROPAGATE • 12-7 
XAB$Q_BDT field *9-2 
XAB$Q_CDT field *9-2 
XAB$Q_EDT field *9-3 
XAB$Q_RDT field *9-3, 13-2 
XAB$V_BLK option* 10-2 
XAB$V_CBT option *8-4 
XAB$V_CHG option* 11-7 
use restriction *11-7 
XAB$V_CR option* 10-2 
XAB$V_CTG option *8-4 
XAB$V_DAT_NCMPR option* 11-7 
XAB$V_DUP option* 11-7 
XAB$V_FTN option* 10-2 
XAB$V_GRP* 12-5 
XAB$V_HRD option • 8-4 
use restrictions • 8-4 
X AB$ V_IDX _NCMPR 

optional use in defining string keys* 11-6 
XAB$V_IDX_NCMPR option* 11-7 
use restriction* 11-7 
XAB$V_KEY_NCMPR 

optional use in defining string keys* 11-6 
XAB$V_KEY_NCMPR option* 11-7 
use restriction *11-7 
XAB$V_NUL 

optional use in defining string keys* 11-6 
XABJV_NUL option* 11-7 
use restriction *11-7 
with XAB$B_NUL field* 11-7 


XAB$V_NUL option in XAB$B_FLG field 
setting for various data types *11-4 
XAB$V_ONC option • 8-4 
XAB$V_0WN • 12-5 
XAB$V_PRN option* 10-2 
X AB$V_PROPAGATE • 12-6 
XAB$V_SYS* 12-5 
XAB$V_WLD* 12-5 
XAB$W_ACLLEN field* 12-3 
determining value* 12-3 
limitation* 12-3 
XAB$W_ACLSIZ field* 12-3 
XAB$W_DEQ field • 8-5 
XAB$W_DFL field* 11-3 
advantages of using* 11-3 
comparing for primary and alternate keys* 11-3 
determining value* 11-3 
use with RAB$V_L0A option *7-13 
XAB$W_DXQ field in XABFHC* 10-3 
XAB$W_FFB field* 10-3 
XAB$W_GBC field in XABFHC* 10-3 
XAB$W_GRP field* 12-4 
XAB$W_IFL field* 11-9 
advantages of using* 11-9 
use with RAB$V_LOA option *7-13 
XAB$W_ITMLST_LEN field* 15-2 
XAB$W_LRL field* 10-4 
use restriction • 10-4 
XAB$W_MBM field* 12-4 
XAB$W_MRL field • 11 -10 

comparing primary key and alternate keys* 
11-10 

XAB$W_MRZ field in XABFHC* 10-4 
determining value* 10-4 
XAB$W_POSO through XAB$B_POS7 field* 

11-11 

requirement to be compatible with XAB$B_ 
SIZO through XAB$B_SIZ7 field* 11-12 
XAB$W_PRO field • 12-5 
default logic • 12-6 
organization* 12-6 

required ordering of arguments* 12-5 
subfield offsets* 12-5 
user classes* 12-6 
XAB$W_PVN field* 14-2 
XAB$W_RFI field • 8-6 

requirement for XAB$C_RFI*8-7 
specifying • 8-6 

XAB$W_RVN field • 9-3, 13-3 
XAB$W_VERLIMIT field in XABFHC* 10-5 
XAB$W_VOL field *8-7 
use restriction • 8-7 
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SXAB ALL-STORE macro »B-14 
argument categories*B-14 
comparing with SXABALL macro *B-14 
requirements • B-14 
XABALL block* 1-3, 8-1 

relationship to FAB fields *8-1 
summary of fields • 8-1 
SXABALL macro *B-13 

argument categories • B-13 
XAB block 

description* 1-3 

naming conventions for FAB* 1-3 
naming conventions for RAB* 1-4 
types for VAX RMS file operations* 1-3 
XAB control block 

program example *4-9 
$XABDAT_STORE macro *B-17 
argument categories • B-17 
argument variations • B-17 
example of use *3-9 
requirements • B-17 
XABDAT block *9-1 
brief description* 1-3 
summary of fields • 9-1 
value selection logic *9-2 
SXABDAT macro *B-16 
$XABFHC_STORE macro *B-19 
argument categories*B-19 
requirements • B-19 
XABFHC block* 10-1 
brief description* 1-3 
summary of fields* 10-1 
use exception* 10-1 
values for shared sequential files* 10-1 
SXABFHC macro *B-18 
$XABKEY_STORE macro *B-22 
argument categories*B-23 
requirements • B-23 
XABKEY block* 11-1 
brief description* 1-3 
data type options* 11-4 
default logic* 11-8 
summary of fields* 11-1 
XAB$B_TKS field *11-14 
XAB$W_MRL field *11-10 
SXABKEY macro *B-20, B-21 
argument categories*B-21 
position and size options*B-21 
$XABPRO_STORE macro *B-26 
argument categories • B-26 
argument exceptions to general rules*B-26 
requirements • B-26 


XABPRO block* 12-1 
brief description* 1-3 
summary of fields* 12-1 
XAB$B_BLN field* 12-4 
XAB$B_COD field* 12-4 
XAB$W_GRP field* 12-4 
SXABPRO macro *B-24 

ASCII radix indicator requirement in MTACC 
argument • B-24 
describing UIC argument • B-25 
example of MTACC argument • B-24 
listing user classes*B-24 
XAB$W_PR0 field requirements • B-24 
XABRDT 

comparing with XABDAT *13-1 
$XABRDT_STORE macro *B-28 
argument categories • B-28 
requirements • B-28 
XABRDT block* 13-1 
brief description* 1-3 
default logic* 13-1 

service use of XAB$Q_RDT and XAB$W_RVN 
fields* 13-1 

summary of fields* 13-1 
use restriction* 13-1 
SXABRDT macro *B-27 
$XABSUM_STORE macro *B-30 
argument categories • B-30 
requirements • B-30 
XABSUM block* 14-1 
brief description* 1-3 
summary of fields* 14-1 
use restriction* 14-1 
SXABSUM macro *B-29 
$XABTRM_STORE macro *B-32 
argument categories • B-32 
requirements • B-32 
XABTRM block* 15-1 
brief deception* 1-4 
requirements to use* 15-1 
summary of fields* 15-1 
SXABTRM macro *B-31 
XITMLIST_LEN field 

requirement for valid terminal driver* 15-1 
XITMLST field 

requirement for valid terminal driver* 15-1 
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